################################################################### # unbound-adblock 0.6 OpenBSD 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) This guide assumes you know how to setup Unbound. If not, there are plenty of online guides to setting up Unbound. An easy introductory guide to setting up Unbound can be found here: https://www.openbsd.org/faq/pf/example1.html#dns OpenBSD Unbound Quick Start: -- Fetch and install example unbound config: $ ftp https://geoghegan.ca/pub/unbound-adblock/0.6/unbound.conf.example # install -m 644 -o root -g wheel unbound.conf.example /var/unbound/etc/unbound.conf -- Configure and enable 'unbound-control': # unbound-control-setup -- (Optional) Configure and enable DNSSEC # doas -u _unbound unbound-anchor -a "/var/unbound/db/root.key" -- Modify unbound.conf to suit your needs: # vi /var/unbound/etc/unbound.conf -- Enable and Start # rcctl enable unbound # rcctl start unbound ################################################################### # Upgrade from unbound-adblock 0.5 ################################################################### 1) Download updated script: $ ftp 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) 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 '6' 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) Configure Unbound as a local recursive DNS server See "Unbound Quick Start" above An example unbound.conf can be found here: https://geoghegan.ca/pub/unbound-adblock/0.6/unbound.conf.example 2) Download script: $ ftp 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) # useradd -s /sbin/nologin -d /var/empty _adblock 4) Install script with appropriate permissions: # install -m 755 -o root -g bin unbound-adblock.sh /usr/local/bin/unbound-adblock 4.b) OPTIONAL: Install RipGrep, mawk, aria2 and/or curl/wget for greatly improved performance: Note: RipGrep is not available on all CPU architectures, use ugrep if affected. # pkg_add ripgrep mawk aria2 wget 5) Create required files: # install -m 644 -o _adblock -g wheel /dev/null /var/unbound/db/adblock.rpz # 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) Give user '_adblock' strict doas permission for the exact commands 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 auth_zone_reload unbound-adblock permit nopass _adblock cmd /usr/sbin/unbound-control args -q flush_zone unbound-adblock permit nopass _adblock cmd /usr/sbin/unbound-control args -q status # Only needed if using old unbound specific 'local-data' backend with '-o unbound' permit nopass _adblock cmd /usr/sbin/unbound-control args -q reload ... 7) Configure unbound-control if it isn't already: # unbound-control-setup 8) Add a few lines to your unbound.conf located BEFORE the forwarders section: (Also add 'remote-control' bits to your config if not there already) ... # Required modules for RPZ module-config: "respip validator iterator" rpz: name: "unbound-adblock" zonefile: "/var/unbound/db/adblock.rpz" rpz-log: yes rpz-log-name: "unbound-adblock" remote-control: control-enable: yes control-interface: 127.0.0.1 ... 9) Restart unbound to reload configuration changes: # rcctl restart unbound 10) Run script manually to parse and load the blocklist data: # doas -u _adblock unbound-adblock 11) Edit _adblock users crontab to run unbound-adblock every night: # crontab -u _adblock -e ... ~ 0~1 * * * -s unbound-adblock ... NOTE: If you're running an OpenBSD release older than 6.7, you'll have to use a workaround: ... @daily sleep $(echo $((RANDOM\%7200+1))) ; unbound-adblock ... --- Please see the crontab(5) man page for further info 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) pf-badhost is highly configurable and extensible, please read the man page for a list of all configuration options and usage examples. x) If you are trying to use very large blocklists, you may need to increase the users limits in /etc/login.conf. You may also need to increase the number of available file descriptors. x) A list of common, popular blocklists may be found here: https://geoghegan.ca/pub/unbound-adblock/data/popular_lists.txt An example configuration file to be loaded with '-C' may be found here: https://geoghegan.ca/pub/unbound-adblock/data/unbound-adblock.conf x) Regarding Cron Jobs: 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. --- If you would like to update 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 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) Note: Use of the '-s' switch prevents 2 instances of unbound-adblock from being run at the same time - which is a good thing. # crontab -u _adblock -e ... ~ */3 * * * -s unbound-adblock ... x) OPTIONAL -- Add the following line to your pf.conf: NOTE: This rule intercepts DNS traffic bound for Google DNS servers. Google mandates the use of their DNS servers in many apps and services. Many devices also use hardcoded Google DNS that cannot be changed. This is both a privacy and freedom concern. This should help rectify the issue: (This rule should be run on your router/gateway) # Replace '$adblock' with the IP address of the Unbound machine ... 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 ... -- Reload your pf rule set: # pfctl -f /etc/pf.conf