NAME unbound-adblock -- Fetch, validate and parse blocklist data into format suitable for ingestion by PF firewall SYNOPSIS unbound-adblock [ -DVhnx ] [ -O [OS type] ] [ -R [integer] ] [ -d [URL] ] [ -l [URL] ] [ -o [option] ] [ -r [domain] ] [ -t [path] ] [ -u [path] ] [ -w [path] ] DEBUGGING OPTIONS unbound-adblock [ -F [curl/fetch/ftp/wget] ] [ -W [path] ] [ -Z [doas/sudo] ] DESCRIPTION unbound-adblock allows you to turn your favorite DNS server software into a DNS firewall. It works by fetching popular lists of known malicious domains and then converting them into 'RPZ' format which is suitable for ingestion by many DNS servers such as Unbound, BIND, PowerDNS, Knot Resolver etc. --- Also supports Unwind as an optional backend for blocking ads on personal devices and on the go. The options are as follows: -D Disable UID checking. unbound-adblock must normally be run as the user '_adblock', and this option disables that check. -O [arg] Specify Operating System type. Valid options are: * Alpine * DragonflyBSD * FreeBSD * Linux * NetBSD * OpenBSD * custom The OS type argument is treated special, as its options are case insensitive. For example, 'OpenBSD' and 'openbsd' are both equally valid arguments for '-O' The 'custom' option allows the user to specify a custom OS type. Arguments '-E', '-F', '-W' and '-Z' and their respective options must also be used when specifying 'custom' as an OS type. -R [int] Specify maximum number of URL fetch attempts. Default is 3. Specify '0' to disable retrys. -V Disable all printing of warning messages. Fatal error messages will still be printed and logged to /var/log/messages. -d [url] Specify URL to fetch domain-only blocklist data from. May be specified multiple times to add multiple blocklists. Depending on specified fetch utility (ftp/fetch/curl/wget etc) unbound-adblock should support HTTP, FTP and local files. -h Print help message and exit. -l [url] Specify URL to fetch /etc/hosts format blocklist data from. May be specified multiple times to add multiple blocklists. Depending on specified fetch utility (ftp/fetch/curl/wget etc) unbound-adblock should support HTTP, FTP and local files. -n Dry run mode. This option will sanity check configuration and return 0 on success and >0 on failure. -o [arg] Options: (case insensitive) * domain Print generated domain list to stdout. This option implies '-x' * log | no-log enable/disable logging to /var/log/unbound-adblock/ * pipefail Use 'set -o pipefail'. This isn't used by default yet as it's a very recent addition to OpenBSD's ksh. * strict | no-strict Enable/disable strict mode. [enabled by default] Strict mode forces unbound-adblock to abort if it fails to fetch one or more blocklists. * uid-check | no-uid-check Enable/disable forced use of user '_adblock'. See '-D' description. * verbose | no-verbose Enable/disable printing of warning messages. See '-V' description. * RPZ Generate RPZ format blocklist [default]. * unbound Generate Unbound local-data blocklist. This is useful if you're trying to use a version of Unbound older than 1.10. * unwind Use unwind as optional backend. This option will parse the list into unwind compatible format and install the list to /var/db/unwind-adblock.db and then reload unwind. -r [arg] Specify domain to whitelist. May be specified multiple times to add additional domains. Supports wildcards such as '*.example.org'. --- Note: Whitelisting is only supported on the default RPZ backend. Note: No input validation is performed on whitelist data - use with care! -t [path] Specify path to text file containing 1 or more URLs pointing to domain-only format blocklists. URLs within text files must be formatted 1 per line. Lines starting with '#' or ';' will be ignored. This option may be specified multiple times. -u [path] Specify path to text file containing 1 or more URLs pointing to /etc/hosts format blocklists. URLs within text file must be formatted 1 per line. Lines starting with '#' or ';' will be ignored. This option may be specified multiple times. -w [path] Specify path to text file containing list of 1 or more domains to whitelist. URLs within text file must be formatted 1 per line. Lines starting with '#' or ';' will be ignored. This option may be specified multiple times. This option supports subdomain wildcards such as '*.example.org' --- Note: Whitelisting is only supported on default RPZ backend. Note: No input validation is performed on whitelist data - use with care! -x This option instructs unbound-adblock to print the generated blocklist to stdout instead of reloading unbound/unwind. This option can be useful for exporting the generated blocklist data for external use. This option may be used in conjunction with '-o' format options to print RPZ, domain-only and unbound local-data blocklists. Use of this option implies '-D' and '-o no-log'. DEBUGGING OPTIONS DESCRIPTION -F [arg] Specify tool for fetching blocklists [curl/fetch/ftp/wget]. -W [path] Specify alternate file path to write blocklist data to. -Z [arg] Specify tool used to perform root priviledged actions, typically 'doas' or 'sudo'. EXIT STATUS The unbound-adblock utility exits 0 on success, and >0 if an error occurs. EXAMPLES The following examples are shown as given to the shell: -- Check configuration validity: $ unbound-adblock -O openbsd -n -- Specify path to list of blocklist URLs: $ unbound-adblock -0 openbsd -u /var/db/urls.txt -- Fetch multiple blocklists and print aggregated domain data: unbound-adblock -O openbsd -o domain -d 'http://example.com/domain.txt' -l 'http://example.com/hosts.txt.gz' -- Disable all checks, logging and printing of warnings: $ unbound-adblock -O openbsd -DV -o no-strict -o no-log -- Feed blocklist to unwind instead of unbound: $ unbound-adblock -O openbsd -o unwind -- Specify custom OS type and requisite info: $ unbound-adblock -O custom -E 'zcat' -F 'fetch' -Z 'sudo' -W '/etc/unbound/adblock.conf' SEE ALSO Installation STANDARDS unbound-adblock supports RPZ, which is a widely adopted standard for implementing DNS filtering. Any DNS server supporting RPZ blocklists should work fine. unbound-adblock does not conform to the POSIX shell spec, but instead aims for KSH compatability. Any shell supporting 'typeset' and KSH array syntax should work fine. unbound-adblock has been confirmed to run on the following shells: * pdksh (and derivatives) * ksh93 * mksh * bash * zsh CAVEATS Whitelisting is only supported for RPZ backends. DNS daemon reload is currently only supported for Unbound and unwind. TO DO Add support for additional RPZ backends such as PowerDNS December 7, 2020 unbound-adblock-0.5