Skip to content

Commit

Permalink
Mostly general polishing for new link targets.
Browse files Browse the repository at this point in the history
  • Loading branch information
@gthess
gthess committed Oct 21, 2022
1 parent 5d345c3 commit aa53f48
Show file tree
Hide file tree
Showing 17 changed files with 1,050 additions and 652 deletions.
216 changes: 111 additions & 105 deletions source/getting-started/configuration.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,148 +4,162 @@ Configuration
Unbound has a vast array of configuration options for advanced use cases, which
can seem a little overwhelming at first. Luckily, all of the defaults are
sensible and secure, so in a lot of environments you can run Unbound without
changing any options. Below we will go through a basic, recommended config, but
feel free to add and experiment with options as you need them.
changing any options.
Below we will go through a basic, recommended configuration, but feel free to
add and experiment with options as you need them.

.. @TODO in the future we can put a forward link to the configuration options +
explanations for advanced users.
..
@TODO in the future we can put a forward link to the configuration options
+ explanations for advanced users.
.. 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 config as its content (or copy the
config to the default config file which can be found during the installation
process).
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 (or
copy the configuration to the default configuration file which can be found
during the installation process).

.. code-block:: bash
server:
# can be uncommented if you do not need user privilige 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 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 config uses `chroot
<https://wiki.archlinux.org/title/chroot>`_ to provide an extra layer of defence
against remote exploits. If Unbound is not starting because it cannot access
files due to permission errors caused by :command:`chroot`, a solution can be to
enter file paths as full pathnames starting at the root of the filesystem
(``/``). Otherwise, if :command:`chroot` is not required you can disable it in
the config.
server:
# can be uncommented if you do not need user privilige protection
# username: ""
.. code-block:: bash
# 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 uses
`chroot <https://wiki.archlinux.org/title/chroot>`_ to provide an extra layer
of defence against remote exploits.
If Unbound is not starting because it cannot access files due to permission
errors caused by :command:`chroot`, a solution can be to enter file paths as
full pathnames starting at the root of the file system (``/``).
Otherwise, if :command:`chroot` is not required you can disable it in the
configuration file:

.. code-block:: text
server:
# disable chroot
chroot: ""
By default Unbound assumes that a user named "unbound" exists, which you can add
this user with an account management tool available on your system (On Linux this
is usually :command:`useradd`). You can also disable this feature by adding
``username: ""`` in the config. If it is enabled,
after the setup, any other user privileges are dropped and the configured
username is assumed. If this user needs access to files (such as the 'trust
anchor' mentioned below) these can be created by executing with ``sudo -u
unbound`` in front of it.
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 :command:`useradd`).
You can also disable this feature by adding ``username: ""`` in the
configuration file:

.. code-block:: bash
.. code-block:: text
server:
# disable user privilige protection
username: ""
.. Important:: Unbound comes with the :doc:`/manpages/unbound-checkconf` tool.
This tool allows you to check the config file for errors before
starting Unbound. It is very convenient because if any errors are
found it tells you where they are, which is particularly useful
when Unbound is already running to avoid failure to restart due
to a configuration error.
If it is enabled, after the setup, any other user privileges are dropped and
the configured username is assumed.
If this user needs access to files (such as the 'trust
anchor' mentioned below), these can be created by executing with ``sudo -u
unbound`` in front of it.


.. important::

Unbound comes with the :doc:`/manpages/unbound-checkconf` tool.
This tool allows you to check the config file for errors before starting
Unbound. It is very convenient because if any errors are found it tells you
where they are, which is particularly useful when Unbound is already
running to avoid failure to restart due to a configuration error.

Testing the setup
-----------------

After running the :command:`unbound-checkconf` command to see if your config
file 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 :doc:`/manpages/unbound` manpage shows that the :option:`-d` flag will start
Unbound in this mode. The manpage also shows that we can use the :option:`-c`
flag to specify the path to the config file, so we can use the one we created.
The :doc:`/manpages/unbound` manpage shows that the :option:`-d<unbound -d>`
flag will start Unbound in this mode.
The manpage also shows that we can use the :option:`-c<unbound -c>` flag to
specify 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 see
what's actually happening (``-v`` or ``-vv``).
what's actually happening (:option:`-v<unbound -v>` or ``-vv``):

.. code-block:: bash
unbound -d -vv -c unbound.conf
unbound -d -vv -c unbound.conf
After Unbound starts normally (and you've sent it some queries) you can
remove the :option:`-v` and :option:`-d` and run the command again. Then Unbound
will fork to the background and run until you either kill it or reboot the
machine.
After Unbound starts normally (and you've sent it some queries) you can remove
the :option:`-v<unbound -v>` and :option:`-d<unbound -d>` and run the command
again.
Then Unbound will fork to the background and run until you either kill it or
reboot the machine.

Set up Remote Control
---------------------

A useful functionality to enable is the :command:`unbound-control`
A useful functionality to enable is the :doc:`/manpages/unbound-control`
command. This makes starting, stopping, and reloading Unbound
easier. To enable this functionality we need to add ``remote-control`` to the
config;
easier.
To enable this functionality we need to add
:ref:`remote-control:<unbound.conf.remote>` to the configuration file:

.. code-block:: bash
.. code-block:: text
remote-control:
# enable remote-control
control-enable: yes
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"
# 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 :command:`unbound-control` command, we need to invoke the
:command:`unbound-control-setup` command. This creates a number of files in the
default install directory. The default install directory is
``/usr/local/etc/unbound/`` on most systems, but some distributions may put it
in ``/etc/unbound/`` or ``/var/lib/unbound``.

Apart from an extensive config file, with just about all the possible
Apart from an extensive configuration file, with just about all the possible
configuration options, :command:`unbound-control-setup` creates the
cryptographic keys necessary for the control option.
cryptographic keys necessary for the control option:

.. code-block:: bash
unbound-control-setup
unbound-control-setup
If you use a username like ``unbound`` in the config to run the daemon (which is
the default setting), you can use :command:`sudo` to create the files in that
user's name, so that the user running Unbound is allowed to read the keys. This
is also a solution if the ``/usr/local/etc/unbound/`` (or any other default
direcotry) directory is write-protected, which is the case for some
If you use a username like ``unbound`` in the configuration to run the daemon
(which is the default setting), you can use :command:`sudo` to create the files
in that user's name, so that the user running Unbound is allowed to read the
keys.
This is also a solution if the ``/usr/local/etc/unbound/`` directory (or any
other default directory) is write-protected, which is the case for some
distributions.

.. code-block:: bash
sudo -u unbound unbound-control-setup
sudo -u unbound unbound-control-setup
You can now control Unbound using the :command:`unbound-control` command. Note
that if your configuration file is not in the default location or not named
``unbound.conf``, the name (and possibly path) need to be provided when using
the command using the :option:`-c` flag.
the command using the :option:`-c<unbound-control -c>` flag.


Set up Trust Anchor (Enable DNSSEC)
Expand All @@ -155,19 +169,19 @@ To enable `DNSSEC <https://www.sidn.nl/en/modern-internet-standards/dnssec>`_,
which we strongly recommend, we need to set up a trust anchor as it allows the
verification of the integrity of the responses to the queries you send.

To help, we can use the :command:`unbound-anchor` command.
To help, we can use the :doc:`/manpages/unbound-anchor` command.


:command:`unbound-anchor` performs the setup by configuring a trust anchor. This
trust anchor will only serve as the initial anchor from builtin values. To keep
this anchor up to date, Unbound must be able to read and write to this file. The
default location that :command:`unbound-anchor` creates this in is determined by
your installation method. Usually the default directory is
``/usr/local/etc/unbound/``.
your installation method.
Usually the default directory is ``/usr/local/etc/unbound/``.

.. code-block:: bash
unbound-anchor
unbound-anchor
Note that using a package manager to install Unbound, on some distributions,
creates the root key during installation. On Ubuntu 20.04.1 LTS for example,
Expand All @@ -177,34 +191,26 @@ is ``/opt/homebrew/etc/unbound/root.key`` If you create the root key yourself
file in the configuration file should be changed to the correct location. To
find out the default location you can use the :command:`unbound-anchor` command
again with the ``-vvv`` option enabled. To enable DNSSEC, we add
``auto-trust-anchor-file`` under the ``server`` clause in the config.
``auto-trust-anchor-file`` under the ``server`` clause in the configuration
file.

.. code-block:: bash
.. code-block:: text
server:
# enable DNSSEC
auto-trust-anchor-file: "/var/lib/unbound/root.key"
server:
# enable DNSSEC
auto-trust-anchor-file: "/var/lib/unbound/root.key"
Note that on some systems the ``/usr/local/etc/unbound/`` directory might be
write-protected.
write-protected.

If the :command:`unbound-control-setup` command fails due to the insufficient
permissions, run the command as the correct user, here we use the user
``unbound`` as this is the default user.

.. code-block:: bash
sudo -u unbound unbound-anchor
sudo -u unbound unbound-anchor
This step is also important when using the ``chroot`` jail.


.. @TODO Write ACL's -> access-control

0 comments on commit aa53f48

Please sign in to comment.