################################################################### # unbound-adblock 0.6 Alpine Linux Installation Instructions # Copyright 2018-2021 Jordan Geoghegan ################################################################### ################################################################### # Table of Contents: ################################################################### * Unbound Configuration Notes * Upgrade Instructions (upgrade from 0.5) * Fresh Install Instructions * Post Install Notes ################################################################### # Notes: ################################################################### 1) These are the unbound-adblock instrucktions for Alpine Linux These instructions are known to work on Alpine 3.9.x 2) If something doesn't work, then the script can be easily tweaked to make it work. See the manpage for info on advanced tweakables. 3) This guide assumes you know how to setup Unbound. If not, there are plenty of online guides to setting up Unbound. Alpine Linux Unbound Quick Start: -- Fetch and install example unbound config: # apk add unbound $ wget https://geoghegan.ca/pub/unbound-adblock/0.6/unbound.conf.example # install -m 644 -o root unbound.conf.example /etc/unbound/unbound.conf -- Configure and enable 'unbound-control': # unbound-control-setup -- Modify unbound.conf to suit your needs: NOTE: You will likely need to use the "unbound-control key" override # vi /etc/unbound/unbound.conf -- Enable and Start # rc-update add unbound # rc-service unbound start ################################################################### # Upgrade from unbound-adblock 0.5 ################################################################### 1) Download updated script: $ wget https://geoghegan.ca/pub/unbound-adblock/0.6/unbound-adblock.sh 2) Install script with appropriate permissions. # install -m 755 -o root -g bin unbound-adblock.sh /usr/local/bin/unbound-adblock 3) Create requisite directories and symlink: Note: unbound-adblock now uses a symlink to simplify portability Note: Your path to adblock.rpz may be different! Note: If you don't want to use a symlink, you can specify path with '-W' flag. # install -d -o root -g wheel -m 755 /var/unbound-adblock # ln -s /etc/unbound/adblock.rpz /var/unbound-adblock/block.db # chown -h root:wheel /var/unbound-adblock/block.db # chmod -h 644 /var/unbound-adblock/block.db 4) Modify cronjobs: Note: unbound-adblock no longer requires specifying host OS type as an argument (See release notes). You will need to adjust your cronjob to accomodate the configuration syntax change. Note: unbound-adblock now opportunistically detects and uses aria2c, curl and/or wget if available. This can improve blocklist fetching performance significantly. Note: If you were using the Unbound local-data backend, you will need to adjust your doas permissions. See heading '7' in the full install instructions below for the exact permissions required. Please read the man page for information on how to configure unbound-adblock. The manpage can be found here: https://geoghegan.ca/pub/unbound-adblock/0.6/man/man.txt To receive notification of new unbound-adblock releases and updates please send an email to 'announce@geoghegan.ca' with a subject line and body of "subscribe unbound-adblock" ################################################################### # Fresh Installation Guide ################################################################### 1) Install and configure Unbound as a local recursive DNS server An example unbound.conf can be found here: https://geoghegan.ca/pub/unbound-adblock/0.6/unbound.conf.example 2) Download script: $ wget https://geoghegan.ca/pub/unbound-adblock/0.6/unbound-adblock.sh 3) Create a new user (we'll call ours "_adblock"): The user should be created with a default shell of "nologin", home folder set to /var/empty/ with no password specified (disables password logins) # adduser -D -s /sbin/nologin _adblock 4) Install script with appropriate permissions: # install -m 755 -o root -g bin unbound-adblock.sh /usr/local/bin/unbound-adblock 5) Create required files: # install -m 644 -o _adblock /dev/null /etc/unbound/adblock.rpz # install -d -o root -g wheel -m 755 /var/unbound-adblock # ln -s /etc/unbound/adblock.rpz /var/unbound-adblock/block.db # chown -h root:wheel /var/unbound-adblock/block.db # chmod -h 644 /var/unbound-adblock/block.db # install -d -o root -g wheel -m 755 /var/log/unbound-adblock # install -o _adblock -g wheel -m 640 /dev/null /var/log/unbound-adblock/unbound-adblock.log # install -o _adblock -g wheel -m 640 /dev/null /var/log/unbound-adblock/unbound-adblock.log.0.gz 6) Install GNU coreutils, 'doas' utility and oksh (OpenBSD ksh): NOTE: 'doas' and 'oksh' are located in the "edge" repository, which is disabled by default. The below commands selectively permit the edge repository for the specified packages: --- # apk add coreutils # apk add doas --update-cache --repository http://dl-3.alpinelinux.org/alpine/edge/main/ --allow-untrusted # apk add oksh --update-cache --repository http://dl-3.alpinelinux.org/alpine/edge/testing/ --allow-untrusted # ln -s /bin/oksh /bin/ksh 6.b) OPTIONAL: Install GNU awk for improved performance: # apk add gawk 7) Give user '_adblock' strict doas permission for the exact command the script needs run as superuser. NOTE: Unlike 'sudo', _ALL_ users must be explicitly granted permission to use doas, even the root user. $ cat /etc/doas.conf ... permit root permit nopass _adblock cmd /usr/sbin/unbound-control args -q status permit nopass _adblock cmd /usr/sbin/unbound-control args -q flush_zone unbound-adblock permit nopass _adblock cmd /usr/sbin/unbound-control args -q auth_zone_reload unbound-adblock # Only needed if using old unbound specific 'local-data' backend with '-o unbound' permit nopass _adblock cmd /usr/sbin/unbound-control args -q reload ... 8) Add a few lines to your unbound.conf located BEFORE the forwarders section: ... # Required modules for RPZ module-config: "respip validator iterator" rpz: name: "unbound-adblock" zonefile: "/etc/unbound/adblock.rpz" rpz-log: yes rpz-log-name: "unbound-adblock" ... 9) Run script manually to parse and load the blocklist data: # doas -u _adblock unbound-adblock 10) Edit _adblock crontab to run unbound-adblock every night at midnight: # crontab -u _adblock -e @daily sleep $(echo $((RANDOM\%7200+1))) unbound-adblock Yay! unbound-adblock is now installed! With the nightly cron job, the list will be regularly updated with the latest known bad hosts. Please read the man page for information on how to configure unbound-adblock. The manpage can be found here: https://geoghegan.ca/pub/unbound-adblock/0.6/man/man.txt To receive notification of new unbound-adblock releases and updates please send an email to 'announce@geoghegan.ca' with a subject line and body of "subscribe unbound-adblock" ################################################################### # Post Install Notes: ################################################################### X) To add custom rules or enable features, or add alternate blocklists, See the "User Configuration Area" located at the top of the script. This area serves as a built in config file, so please feel free to edit it and experiment with all the features available within. --- Note: Most options can also be configured from the command line X) Regarding Shells: unbound-adblock requires a shell that supports 'typeset' and ksh array syntax. Alpine's default /bin/sh doesn't behave the way we need it to, so a modern shell should be installed. Five different shells have been tested and confirmed to work: * oksh (OpenBSD's ksh) * ksh93 * mksh * zsh * bash ... If you wish to use one of the above shells, you'll have to make a few changes. To make these changes automatically (replace "zsh" with your preferred shell): # sed -i '1 s/ksh/zsh/' /usr/local/bin/unbound-adblock X) Regarding Cron Jobs: Over the past year I've noticed a number of list host servers going down at midnight in populated timezones (ie West Coast, East Coast and Western Europe). To be respectful (and to avoid overloading list providers servers) we have cron jobs scheduled to run at a random time within a defined interval. --- With the new default cron job, unbound-adblock will be run every night at some point between midnight and 2AM, and thus distributing the load of thousands of queries from numerous users over a 2 hour period rather than a matter of seconds. X) If you would like to update the unbound-adblock blocklists at a more frequent interval you can use a modified cron job: --- It is essential that you make use of the crontab randomization feature to ensure use of unbound-adblock remains respecful of blocklist provider resources. --- The following example runs unbound-adblock every 3 to 4 hours at a random minute (this avoids flooding the server with traffic at exactly XX:00) --- Run unbound-adblock every 3 hours Example: (you can change '*/3' to '*/4' to run every 4 hours) # crontab -u _adblock -e ... 0 */3 * * * sleep $(echo $((RANDOM\%3600+1))) ; unbound-adblock ... X) Google mandates the use of their DNS servers in many apps and services and many devices also use hardcoded Google DNS that cannot be changed. This is both a privacy and freedom concern. If you can, redirect all DNS traffic to the machine running Unbound. Example PF ruleset: (This rule should be run on your router/gateway) ... table {8.8.8.8 8.8.4.4} table {2001:4860:4860::8888 2001:4860:4860::8844} pass in quick to rdr-to $adblock pass in quick to rdr-to $adblock6 ...