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.

138 lines
9.6 KiB

  1. # Simple AdBlock
  2. A simple DNSMASQ-based AdBlocking service for OpenWrt/LEDE Project. Loosely based on [bole5's](https://forum.openwrt.org/profile.php?id=45571) idea with major performance improvements, added features and Web UI (as a separate package); inspired by @dibdot's innovation.
  3. ## Features
  4. - Supports OpenWrt Designated Driver and LEDE Project.
  5. - Super-fast due to the nature of supported block lists and backgrounding of already downloaded data while next list is downloading.
  6. - Supports both hosts files and domains lists for blocking (to keep it lean and fast).
  7. - Everything is configurable from Web UI.
  8. - Allows you to easily add your own domains to whitelist or blacklist.
  9. - Allows you to easily add URLs to your own blocked hosts or domains lists to block/whitelist (just put whitelisted domains one per line).
  10. - Requires no configuration for the download utility wherever you want to use wget/libopenssl or uclient-fetch/libustream-mbedtls.
  11. - Installs dependencies automatically (DD/LEDE-default uclient-fetch libustream-mbedtls).
  12. - Doesn't stay in memory -- creates the list of blocked domains and then uses DNSMASQ and firewall rules to serve "domain not found reply".
  13. - As some of the default lists are using https, reliably works with either wget/libopenssl or uclient-fetch/libustream-mbedtls.
  14. - Very lightweight and easily hackable, the whole script is just one /etc/init.d/simple-adblock file.
  15. - Logs single entry in the system log with the number of blocked domains if verbosity is set to 0.
  16. - Retains the downloaded/sorted adblocking list on service stop and reuses it on service start (use reload if you want to force re-download of the list).
  17. - Blocks ads served over https.
  18. - Proudly made in Canada, using locally-sourced electrons.
  19. If you want a more robust AdBlocking, supporting free memory detection and complex block lists, supporting IDN, check out [@dibdot's adblock](https://github.com/openwrt/packages/tree/master/net/adblock/files).
  20. ## Screenshot (luci-app-simple-adblock)
  21. ![screenshot](https://raw.githubusercontent.com/stangri/openwrt_packages/master/screenshots/simple-adblock/screenshot06.png "screenshot")
  22. ## Requirements
  23. This service requires the following packages to be installed on your router: ```dnsmasq``` or ```dnsmasq-full``` and either ```ca-certificates```, ```wget``` and ```libopenssl``` (for OpenWrt 15.05.1) or ```uclient-fetch``` and ```libustream-mbedtls``` (for OpenWrt DD trunk and all LEDE Project builds). Additionally installation of ```coreutils-sort``` is highly recommended as it speeds up blocklist processing.
  24. To satisfy the requirements for connect to your router via ssh and run the following commands:
  25. ### OpenWrt 15.05.1 Requirements
  26. ```sh
  27. opkg update; opkg install ca-certificates wget libopenssl coreutils-sort dnsmasq
  28. ```
  29. ### LEDE Project 17.01.x and OpenWrt 18.xx or later Requirements
  30. ```sh
  31. opkg update; opkg install uclient-fetch libustream-mbedtls coreutils-sort dnsmasq
  32. ```
  33. ### IPv6 Support
  34. For IPv6 support additionally install ```ip6tables-mod-nat``` and ```kmod-ipt-nat6``` packages from Web UI or run the following in the command line:
  35. ```sh
  36. opkg update; opkg install ip6tables-mod-nat kmod-ipt-nat6
  37. ```
  38. ### Speed up blocklist processing with coreutils-sort
  39. The ```coreutils-sort``` is an optional, but recommended package as it speeds up sorting and removing duplicates from the merged list dramatically. If opkg complains that it can't install ```coreutils-sort``` because /usr/bin/sort is already provided by busybox, you can run ```opkg --force-overwrite install coreutils-sort```.
  40. ## Unmet dependencies
  41. If you are running a development (trunk/snapshot) build of OpenWrt/LEDE Project on your router and your build is outdated (meaning that packages of the same revision/commit hash are no longer available and when you try to satisfy the [requirements](#requirements) you get errors), please flash either current LEDE release image or current development/snapshot image.
  42. ## How to install
  43. Install ```simple-adblock``` and ```luci-app-simple-adblock``` packages from Web UI or run the following in the command line:
  44. ```sh
  45. opkg update; opkg install simple-adblock luci-app-simple-adblock
  46. ```
  47. If ```simple-adblock``` and ```luci-app-simple-adblock``` packages are not found in the official feed/repo for your version of OpenWrt/LEDE Project, you will need to [add a custom repo to your router](#add-custom-repo-to-your-router) first.
  48. ### Add custom repo to your router
  49. If your router is not set up with the access to repository containing these packages you will need to add custom repository to your router by connecting to your router via ssh and running the following commands:
  50. #### OpenWrt 15.05.1 Instructions
  51. ```sh
  52. opkg update; opkg install ca-certificates wget libopenssl
  53. echo -e -n 'untrusted comment: LEDE usign key of Stan Grishin\nRWR//HUXxMwMVnx7fESOKO7x8XoW4/dRidJPjt91hAAU2L59mYvHy0Fa\n' > /tmp/stangri-repo.pub && opkg-key add /tmp/stangri-repo.pub
  54. ! grep -q 'stangri_repo' /etc/opkg/customfeeds.conf && echo 'src/gz stangri_repo https://raw.githubusercontent.com/stangri/openwrt-repo/master' >> /etc/opkg/customfeeds.conf
  55. opkg update
  56. opkg install simple-adblock luci-app-simple-adblock
  57. ```
  58. #### LEDE Project 17.01.x and OpenWrt 18.06.x Instructions
  59. ```sh
  60. opkg update
  61. opkg list-installed | grep -q uclient-fetch || opkg install uclient-fetch
  62. opkg list-installed | grep -q libustream || opkg install libustream-mbedtls
  63. echo -e -n 'untrusted comment: LEDE usign key of Stan Grishin\nRWR//HUXxMwMVnx7fESOKO7x8XoW4/dRidJPjt91hAAU2L59mYvHy0Fa\n' > /tmp/stangri-repo.pub && opkg-key add /tmp/stangri-repo.pub
  64. ! grep -q 'stangri_repo' /etc/opkg/customfeeds.conf && echo 'src/gz stangri_repo https://raw.githubusercontent.com/stangri/openwrt-repo/master' >> /etc/opkg/customfeeds.conf
  65. opkg update
  66. opkg install simple-adblock luci-app-simple-adblock
  67. ```
  68. ## Default Settings
  69. Default configuration has service disabled (use Web UI to enable/start service or run ```uci set simple-adblock.config.enabled=1```) and selected ad/malware lists suitable for routers with 64Mb RAM. The configuration file has lists in descending order starting with biggest ones, comment out or delete the lists you don't want or your router can't handle.
  70. ## How to customize
  71. You can use Web UI (found in Services/Simple AdBlock) to add/remove/edit links to:
  72. - hosts files (127.0.0.1 or 0.0.0.0 followed by space and domain name per line) to be blocked.
  73. - domains lists (one domain name per line) to be blocked.
  74. - domains lists (one domain name per line) to be whitelisted. It is useful if you want to run simple-adblock on multiple routers and maintain one centralized whitelist which you can publish on a web-server.
  75. Please note that these lists **have** to include either ```http://``` or ```https://``` (or, if ```curl``` is installed the ```file://```) prefix. Some of the top block lists (both hosts files and domains lists) suitable for routers with at least 8MB RAM are used in the default simple-adblock installation.
  76. You can also use Web UI to add individual domains to be blocked or whitelisted.
  77. If you want to use CLI to customize simple-adblock config, you can probably figure out how to do it by looking at the contents of ```/etc/config/simple-adblock``` or output of the ```uci show simple-adblock``` command.
  78. ## How to use
  79. Once the service is enabled in the [config file](#default-settings), run ```/etc/init.d/simple-adblock start``` to start the service. Either ```/etc/init.d/simple-adblock restart``` or ```/etc/init.d/simple-adblock reload``` will only restart the service and/or re-donwload the lists if there were relevant changes in the config file since the last successful start. Had the previous start resulted in any error, either ```/etc/init.d/simple-adblock start```, ```/etc/init.d/simple-adblock restart``` or ```/etc/init.d/simple-adblock reload``` will attempt to re-download the lists.
  80. If you want to force simple-adblock to re-download the lists, run ```/etc/init.d/simple-adblock download```.
  81. If you want to check if the specific domain (or part of the domain name) is being blocked, run ```/etc/init.d/simple-adblock check test-domain.com```.
  82. ## How does it work
  83. This service downloads (and processes in the background, removing comments and other useless data) lists of hosts and domains to be blocked, combines those lists into one big block list, removes duplicates and sorts it and then removes your whitelisted domains from the block list before converting to to dnsmasq-compatible file and restarting dnsmasq. The result of the process is that dnsmasq returns "domain not found" for the blocked domains.
  84. If you specify ```google.com``` as a domain to be whitelisted, you will have access to ```google.com```, ```www.google.com```, ```analytics.google.com```, but not fake domains like ```email-google.com``` or ```drive.google.com.verify.signin.normandeassociation.com``` for example. If you only want to allow ```www.google.com``` while blocking all other ```google.com``` subdomains, just specify ```www.google.com``` as domain to be whitelisted.
  85. In general, whatever domain is specified to be whitelisted; it, along with with its subdomains will be whitelisted, but not any fake domains containing it.
  86. ## Documentation / Discussion
  87. Please head [LEDE Project Forum](https://forum.lede-project.org/t/simple-adblock-fast-lean-and-fully-uci-luci-configurable-adblocking/1327/) for discussion of this package.
  88. ## Thanks
  89. I'd like to thank everyone who helped create, test and troubleshoot this service. Special thanks to [@hnyman](https://github.com/hnyman) for general package/luci guidance, [@dibdot](https://github.com/dibdot) for general guidance and block-list optimization code and [@ckuethe](https://github.com/ckuethe) for the curl support, non-ASCII filtering and compressed cache code.