UNBOUND-ADBLOCK(8) System Manager's Manual UNBOUND-ADBLOCK(8)

unbound-adblock — create blocklists for use with unbound

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

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:

The options are as follows:

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.
Disable UID checking. unbound-adblock must normally be run as the user _adblock, and this option disables that check.
maxprocs
Specify maximum number of processes to run in parallel. Default is 3. Specify 0 to disable parallelism.
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.
Override HTTP user agent.
Disable all printing of warning messages. Fatal error messages will still be printed to stderr and logged to /var/log/messages.
output-file
Specify alternate file path to write blocklist data to.
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.
Print help message and exit.
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.
Dry run mode. This option will sanity check configuration and return 0 on success and >0 on failure.
long-option
See LONG OPTIONS.
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.

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.
Print version information and exit.
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.

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.

The (case insensitive) options are as follows:

|
Enable/Disable the use of the CUSTOM_FILTER function from an external config file specified with -C. Disabled by default.
|
Enable/Disable logging warning and info messages to syslog and logging generated blocklists to /var/log/unbound-adblock. Enabled by default.
|
Enable/disable strict mode. Strict mode forces unbound-adblock to abort if it fails to fetch one or more blocklists. Enabled by default.
|
Enable/disable forced use of user _adblock. See -D description. Enabled by default.
|
Enable/disable printing of warning messages. See -V description. Enabled by default.

Export Functions:

Export raw domains to stdout. This option implies -x.
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.

Generate RPZ format blocklist. This is the default blocklist format.
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.
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.

Return an 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.
Return a 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.
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.
Return a response for all domains in the blocklist. This amounts to returning or 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 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.

Use aria2c.
Use curl.
Use the FreeBSD fetch(1) utility.
Use the OpenBSD ftp(1) utility.
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.

Use GNU grep.
Use the systems default grep(1).
Use ripgrep.
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.

Use the systems default awk(1).
Use GNU awk.
Use GoAWK.
Use mawk.

The unbound-adblock utility exits 0 on success, and >0 if an error occurs.

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

unbound.conf(5), unbound(8), unwind(8)

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:

Jordan Geoghegan <jordan@geoghegan.ca>

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.

October 28, 2021 OpenBSD 7.0