Unbound has a vast array of configuration options for advanced use cases, whichcan seem a little overwhelming at first. Luckily, all of the defaults aresensible and secure, so in a lot of environments you can run Unbound withoutchanging any options.Below we will go through a basic, recommended configuration, but feel free toadd and experiment with options as you need them.
Note
The instructions in this page assume that Unbound is already installed.
The basic configuration which you can use out of the box is shown below.To use it, you need to create a file with this configuration as its content (orcopy the configuration to the default configuration file which can be foundduring the installation process).
server: # can be uncommented if you do not need user privilege protection # username: "" # can be uncommented if you do not need file access protection # chroot: "" # location of the trust anchor file that enables DNSSEC. note that # the location of this file can be elsewhere auto-trust-anchor-file: "/usr/local/etc/unbound/root.key" # auto-trust-anchor-file: "/var/lib/unbound/root.key" # send minimal amount of information to upstream servers to enhance privacy qname-minimisation: yes # specify the interface to answer queries from by ip-address. interface: 0.0.0.0 # interface: ::0 # addresses from the IP range that are allowed to connect to the resolver access-control: 192.168.0.0/16 allow # access-control: 2001:DB8/64 allow
By default the Unbound configuration useschroot to provide an extra layerof defence against remote exploits.If Unbound is not starting because it cannot access files due to permissionerrors caused by chroot, a solution can be to enter file paths asfull pathnames starting at the root of the file system (/).Otherwise, if chroot is not required you can disable it in theconfiguration file:
server: # disable chroot chroot: ""
By default Unbound assumes that a user named “unbound” exists.You can add this user with an account management tool available on your system;on Linux this is usually useradd).You can also disable this feature by adding username: "" in theconfiguration file:
server: # disable user privilege protection username: ""
If it is enabled, after the setup, any other user privileges are dropped andthe configured username is assumed.If this user needs access to files (such as the ‘trustanchor’ mentioned below), these can be created by executing with sudo -uunbound in front of it.
Important
Unbound comes with the unbound-checkconf(8) tool.This tool allows you to check the config file for errors before startingUnbound. It is very convenient because if any errors are found it tells youwhere they are, which is particularly useful when Unbound is alreadyrunning to avoid failure to restart due to a configuration error.
Testing the setup¶
After running the unbound-checkconf command to see if your configfile is correct, you can test your setup by running Unbound in “debug” mode.This allows you to see what is happening during startup and catch any errors.The unbound(8) manpage shows that the -dflag will start Unbound in this mode.The manpage also shows that we can use the -c flag tospecify the path to the configuration file, so we can use the one we created.We also recommend increasing the verbosity of the logging to 1 or 2, to seewhat’s actually happening (-v or -vv):
unbound -d -vv -c unbound.conf
After Unbound starts normally (and you’ve sent it some queries) you can removethe -v and -d and run the commandagain.Then Unbound will fork to the background and run until you either kill it orreboot the machine.
You may run into an error where Unbound tells you it cannot bind to0.0.0.0 as it’s already in use. This is because the system resolversystemd-resolved is already running on that port. You can go around this bychanging the IP address in the config to 127.0.0.1. This looks like:
server: # specify the interface to answer queries from by ip-address. interface: 127.0.0.1
If you want to change this behaviour, on this pagewe show how to change the system resolver to be Unbound.
Set up Remote Control¶
A useful functionality to enable is the unbound-control(8)command. This makes starting, stopping, and reloading Unboundeasier.To enable this functionality we need to addremote-control: to the configuration file:
remote-control: # enable remote-control control-enable: yes # location of the files created by unbound-control-setup # server-key-file: "/usr/local/etc/unbound/unbound_server.key" # server-cert-file: "/usr/local/etc/unbound/unbound_server.pem" # control-key-file: "/usr/local/etc/unbound/unbound_control.key" # control-cert-file: "/usr/local/etc/unbound/unbound_control.pem"
To use the unbound-control command, we need to invoke theunbound-control-setup command. This creates a number of files in thedefault install directory. The default install directory is/usr/local/etc/unbound/ on most systems, but some distributions may put itin /etc/unbound/ or /var/lib/unbound.
unbound-control-setup creates the cryptographic keys necessary for the control option:
unbound-control-setup
If you use a username like unbound in the configuration to run the daemon(which is the default setting), you can use sudo to create the filesin that user’s name, so that the user running Unbound is allowed to read thekeys.This is also a solution if the /usr/local/etc/unbound/ directory (or anyother default directory) is write-protected, which is the case for somedistributions.
sudo -u unbound unbound-control-setup
You can now control Unbound using the unbound-control command. Notethat if your configuration file is not in the default location or not namedunbound.conf, the name (and possibly path) need to be provided when usingthe command using the -c flag.
Set up Trust Anchor (Enable DNSSEC)¶
To enable DNSSEC,which we strongly recommend, we need to set up a trust anchor as it allows theverification of the integrity of the responses to the queries you send.
To help, we can use the unbound-anchor(8) command.
unbound-anchor performs the setup by configuring a trust anchor. Thistrust anchor will only serve as the initial anchor from built-in values. To keepthis anchor up to date, Unbound must be able to read and write to this file. Thedefault location that unbound-anchor creates this in is determined byyour installation method.Usually the default directory is /usr/local/etc/unbound/.
Note
During the dynamic linking, this command could output an error aboutloading shared libraries. This is remedied by running ldconfig to resetthe dynamic library cache.
unbound-anchor
Note that using a package manager to install Unbound, on some distributions,creates the root key during installation. On Ubuntu 22.04 LTS for example,this location is /var/lib/unbound/root.key. On macOS Big Sur this locationis /opt/homebrew/etc/unbound/root.key If you create the root key yourself(by using the unbound-anchor command), then the path to the anchorfile in the configuration file should be changed to the correct location. Tofind out the default location you can use the unbound-anchor commandagain with the -vvv option enabled. To enable DNSSEC, we addauto-trust-anchor-file under the server clause in the configurationfile.
server: # enable DNSSEC auto-trust-anchor-file: "/var/lib/unbound/root.key"
Note that on some systems the /usr/local/etc/unbound/ directory might bewrite-protected.
If the unbound-anchor command fails due to the insufficientpermissions, run the command as the correct user, here we use the userunbound as this is the default user.
sudo -u unbound unbound-anchor
This step is also important when using the chroot jail.
