UNBOUND-ADBLOCK(8) System Manager's Manual UNBOUND-ADBLOCK(8) NAME unbound-adblock - create blocklists for use with unbound SYNOPSIS unbound-adblock [-DVnx] [-C config-file] [-P maxprocs] [-R retry-limit] [-U user-agent] [-W output-file] [-f blocklist-file] [-l url-file] [-o long-option] [-r domain] [-u url] [-w whitelist-file] [file ...] unbound-adblock -h | -v 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(8), bind(2), PowerDNS and Knot Resolver. It also supports unwind(8) as an optional backend to facilitate DNS firewalling on personal devices and on the go. By default unbound-adblock will attempt to feed generated RPZ blocklist data into unbound(8). If the -x or -o export-raw options are specified then generated data will be output to stdout. Common uses include: o Blocking ads, malware, trackers and other undesirable content o Generating and converting between various blocklist formats o Merging, sorting and validating domain block lists o Logging RPZ policy enforcement actions to syslog (via Unbound) o And much much more! The options are as follows: -C config-file Specify local path to configuration file. To avoid having your config file potentially nullify or clobber conflicting command- line arguments, specify this flag first. -D Disable UID checking. unbound-adblock must normally be run as the user _adblock, and this option disables that check. -P maxprocs Specify maximum number of processes to run in parallel. Default is 3. Specify 0 to disable parallelism. -R retry-limit Specify maximum number of URL fetch attempts. Default is 5. Specify 0 to disable retries. Semantics for this option differ based upon which URL fetch utility has been specified. -U Override HTTP user agent. -V Disable all printing of warning messages. Fatal error messages will still be printed to stderr and logged to /var/log/messages. -W output-file Specify alternate file path to write blocklist data to. -f blocklist-file Specify path to text file on local file system containing blocklist data. This option uses the readlink(1) utility to canonicalize file paths. -h Print help message and exit. -l url-file Specify path to text file containing a list of one or more blocklist URLs. URLs within text file must be formatted one per line. Lines starting with hash mark (`#') or semi-colon (`;') will be ignored. Works with HTTP(S) and FTP URLs. Additional URL format support is dependent upon specified URL fetch utility. This option may be specified multiple times. -n Dry run mode. This option will sanity check configuration and return 0 on success and >0 on failure. -o long-option See LONG OPTIONS. -r domain Specify domain to whitelist. This option may be specified multiple times. Supports wildcards such as `*.example.org' when used with the RPZ backend. Note: Whitelisting is only supported on the RPZ and Unbound local-data backends. -u url Specify a single URL to fetch blocklist data from. Works with HTTP(S) and FTP URLs. Additional URL format support is dependent upon specified URL fetch utility. This option may be specified multiple times. -v Print version information and exit. -w whitelist-file 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 hash mark (`#') or semi-colon (`;') will be ignored. This option supports subdomain wildcards such as `*.example.org' when used with the RPZ backend. This option may be specified multiple times. Note: Whitelisting is only supported on the RPZ and local-data backends. -x This option instructs unbound-adblock to export the generated blocklist data to stdout without interacting with unbound(8) or unwind(8). 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(8) local-data format blocklists. Use of this option implies -D and -o no-log. LONG OPTIONS The (case insensitive) options are as follows: custom-filter | no-custom-filter Enable/Disable the use of the CUSTOM_FILTER function from an external config file specified with -C. Disabled by default. log | no-log Enable/Disable logging warning and info messages to syslog and logging generated blocklists to /var/log/unbound-adblock. Enabled by default. strict | no-strict Enable/disable strict mode. Strict mode forces unbound-adblock to abort if it fails to fetch one or more blocklists. Enabled by default. uid-check | no-uid-check Enable/disable forced use of user _adblock. See -D description. Enabled by default. verbose | no-verbose Enable/disable printing of warning messages. See -V description. Enabled by default. Export Functions: domain Export raw domains to stdout. This option implies -x. export-raw Export raw blocklist data with no embedded statistics, dates or comments etc. All info and warning messages are suppressed. Fatal error messages will be printed to stderr. This option may be used in conjunction with the below options to specify formatting and response preferences. This option implies -x. Blocklist Output Formatting: Note: If multiple output formats are specified, the last specified option is used. RPZ Generate RPZ format blocklist. This is the default blocklist format. unbound Generate unbound(8) local-data blocklist. This option is useful if you're trying to use a version of Unbound older than 1.10 or if you have niche requirements. Unlike the default RPZ blocking method, this option requires unbound(8) to perform a full cache flush every time it reloads it's blocklist data. unwind Generate unwind(8) compatible blocklist data and use unwindctl(8) to interact with unwind(8). If a domain from the blocklist is queried, unwind(8) answers with a return code of REFUSED. Custom DNS responses: Notes: If multiple custom DNS responses are specified, the last specified option is used. These options have no effect when used with the unwind(8) backend. dns-nxdomain Return an NXDOMAIN response for all domains in the blocklist. This option works with the RPZ and unbound(8) local-data backends, and is the default for both. dns-nodata Return a NODATA response for all domains in the blocklist. Some software may misbehave when served NXDOMAIN responses for blocking, and often times in those cases using a NODATA response instead can solve the issue. This option works with the RPZ and unbound(8) local-data backends. Use with the local-data backend requires unbound(8) version 1.13.1 or higher. dns-refused Return a REFUSED response for all domains in the blocklist. Some software may misbehave when served NXDOMAIN responses for blocking, and often times in those cases using a REFUSED response instead can solve the issue. This option works only with the unbound(8) local-data backend. dns-null Return a NULL response for all domains in the blocklist. This amounts to returning 0.0.0.0 or ::0 for all blocked queries. This option works only with the unbound(8) local-data backend. This option requires unbound(8) version 1.13.1 or higher. Debugging options: print-debug Print debugging information and statistics. Utility options: The following URL fetch utilities are supported and unless overridden by specifying one of the options below, will be used in the following order of preference if found on the system: aria2c, wget, curl, fetch, ftp. aria2c Use aria2c. curl Use curl. fetch Use the FreeBSD fetch(1) utility. ftp Use the OpenBSD ftp(1) utility. wget Use wget. The following grep(1) utilities are supported and unless overridden by specifying one of the options below, will be used in the following order of preference if found on the system: ripgrep, ugrep, ggrep, grep. ggrep Use GNU grep. grep Use the systems default grep(1). rg Use ripgrep. ugrep Use ugrep. The following awk(1) utilities are supported and unless overridden by specifying one of the options below, will be used in the following order of preference if found on the system: mawk, gawk, goawk, awk. awk Use the systems default awk(1). gawk Use GNU awk. goawk Use GoAWK. mawk Use mawk. EXIT STATUS The unbound-adblock utility exits 0 on success, and >0 if an error occurs. EXAMPLES Check configuration validity: $ unbound-adblock -nC /etc/unbound-adblock.conf Fetch and process blocklist URLs from local list in bulk and export aggregated RPZ blocklist to stdout: $ unbound-adblock -xl /var/db/urls.txt Specify list of custom whitelist rules and blocklist URLs: $ unbound-adblock -w /var/db/whitelist.txt -l /var/db/urls.txt Specify individual whitelist rules and blocklist URLs: $ unbound-adblock -r example.com -u https://example.com/file.txt Specify custom backend with custom response code: $ unbound-adblock -o unbound -o dns-refused Disable all checks, logging and printing of warnings: $ unbound-adblock -DV -o no-strict -o no-log Feed blocklist to unwind(8) instead of Unbound: $ unbound-adblock -o unwind SEE ALSO unbound.conf(5), unbound(8), unwind(8) STANDARDS unbound-adblock supports RPZ, which is a widely adopted standard for implementing DNS filtering. Any DNS server supporting RPZ should be compatible with the unbound-adblock generated RPZ data. unbound-adblock does not conform to the POSIX shell spec, but instead aims for ksh(1) compatibility. Any shell supporting typeset, ksh(1) array and double bracket syntax should work fine. unbound-adblock has been confirmed to run on the following shells: o oksh (OpenBSD ksh) o ksh93 o mksh o bash o zsh AUTHORS Jordan Geoghegan CAVEATS Whitelisting is only supported for RPZ and unbound(8) local-data backends. DNS daemon reload is currently only supported for unbound(8) and unwind(8). The unwind(8) backend does not support wildcards, whitelisting or custom DNS return codes. OpenBSD 7.0 October 28, 2021 OpenBSD 7.0