Self sign-up has been disabled due to increased spam activity. If you want to get access, please send an email to a project owner (preferred) or at gitlab(at)nic(dot)cz. We apologize for the inconvenience.
Easiest way to configure Knot Resolver is to put YAML configuration in ``/etc/knot-resolver/config.yml`` file.
You can start exploring the configuration by continuing in this chapter or look at the complete :ref:`configuration <configuration-chapter>` documentation.
.. contents::
:depth: 1
:local:
:depth: 1
:local:
Complete examples of configuration files can be found `here <https://gitlab.nic.cz/knot/knot-resolver/tree/master/etc/config>`_.
Examples are also installed as documentation files, typically in ``/usr/share/doc/knot-resolver/examples/`` directory (location may be different based on your Linux distribution).
.. tip::
You can use :ref:`kresctl <manager-client>` utility to **validate** your configuration before pushing it into the running resolver.
It should help prevent many typos in the configuration.
.. code-block::
$ kresctl validate /etc/knot-resolver/config.yml
If you update the configuration file while Knot Resolver is running, you can force the resolver to **reload** it by invoking a ``systemd`` reload command.
.. code-block::
$ systemctl reload knot-resolver.service
.. note::
**Reloading configuration** can fail even when your configuration is valid, because some options cannot be changed while running. You can always find an explanation of the error in the log accesed by the ``journalctl -eu knot-resolver`` command.
Easiest way to configure Knot Resolver is to put configuration to ``/etc/knot-resolver/config.yml`` file.
===============================
Listening on network interfaces
===============================
The first thing you will probably want to configure are the network interfaces to listen to.
The following example instructs the resolver to receive standard unencrypted DNS queries on ``192.0.2.1`` and ``2001:db8::1`` IP addresses.
...
...
@@ -32,54 +60,204 @@ For more details look at the :ref:`network configuration <config-network>`.
On machines with multiple IP addresses on the same interface avoid listening on wildcards ``0.0.0.0`` or ``::``.
Knot Resolver could answer from different IP addresses if the network address ranges overlap, and clients would refuse such a response.
You can also start exploring the configuration by reading about :ref:`common use cases <usecases-chapter>` or look at the complete :ref:`configuration <configuration-chapter>` documentation.
Complete configurations files examples can be found `here <https://gitlab.nic.cz/knot/knot-resolver/tree/master/etc/config>`_.
Examples are also installed as documentation files, typically in ``/usr/share/doc/knot-resolver/examples/`` directory (location may be different based on your Linux distribution).
.. _examle-internal:
==========
Validation
==========
==========================
Example: Internal Resolver
==========================
Knot Resolver's configuration follows strict schema for validation.
This is an example of typical configuration for company-internal resolver which is not accessible from outside of company network.
You can use :ref:`kresctl <manager-client>` utility to validate your configuration before pushing it into the running resolver.
It should help prevent many typos in the configuration.
^^^^^^^^^^^^^^^^^^^^^
Internal-only domains
^^^^^^^^^^^^^^^^^^^^^
.. code-block::
An internal-only domain is a domain not accessible from the public Internet.
In order to resolve internal-only domains a query policy has to be added to forward queries to a correct internal server.
This configuration will forward two listed domains to a DNS server with IP address ``192.0.2.44``.
$ kresctl validate /etc/knot-resolver/config.yml
.. code-block:: yaml
policy:
======
Reload
======
If you change the configuration while the resolver is running, you can push it into the running resolver by invoking a ``systemd`` reload command.
**Reloading configuration** can fail even when your configuration is valid, because some options cannot be changed while running. You can always find an explanation of the error in the log accesed by the ``journalctl -eu knot-resolver`` command.
.. _examle-isp:
==============
Management API
==============
=====================
Example: ISP Resolver
=====================
The configuration can be also changed at runtime through the provided :ref:`management API <manager-api>`.
Changing the configuration through the API does not introduce any downtime to the provided service.
The following configuration is typical for Internet Service Providers who offer DNS resolver
service to their own clients in their own network. Please note that running a *public DNS resolver*
is more complicated and not covered by this example.
.. note::
^^^^^^^^^^^^^^^^^^^^^^
Limiting client access
^^^^^^^^^^^^^^^^^^^^^^
Any changes made during runtime are not persistent unless you modify the configuration file yourself.
With exception of public resolvers, a DNS resolver should resolve only queries sent by clients in its own network. This restriction limits attack surface on the resolver itself and also for the rest of the Internet.
The API can be used from the command-line with the :ref:`kresctl <manager-client>` utility.
For example, you can change the number of daemon workers.
In a situation where access to DNS resolver is not limited using IP firewall, you can implement access restrictions which combines query source information with :ref:`policy rules <mod-policy>`.
Following configuration allows only queries from clients in subnet ``192.0.2.0/24`` and refuses all the rest.
DNS queries can be used to gather data about user behavior.
Knot Resolver can be configured to forward DNS queries elsewhere,
and to protect them from eavesdropping by TLS encryption.
.. warning::
Latest research has proven that encrypting DNS traffic is not sufficient to protect privacy of users.
For this reason we recommend all users to use full VPN instead of encrypting *just* DNS queries.
Following configuration is provided **only for users who cannot encrypt all their traffic**.
For more information please see following articles:
- Simran Patil and Nikita Borisov. 2019. What can you learn from an IP? (`slides <https://irtf.org/anrw/2019/slides-anrw19-final44.pdf>`_, `the article itself <https://dl.acm.org/authorize?N687437>`_)
- `Bert Hubert. 2019. Centralised DoH is bad for Privacy, in 2019 and beyond <https://labs.ripe.net/Members/bert_hubert/centralised-doh-is-bad-for-privacy-in-2019-and-beyond>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Forwarding over TLS protocol (DNS-over-TLS)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Forwarding over TLS protocol protects DNS queries sent out by resolver.
It can be configured using :ref:`TLS forwarding <tls-forwarding>` which provides methods for authentication.
.. It can be configured using :ref:`policy.TLS_FORWARD <tls-forwarding>` which provides methods for authentication.
See list of `DNS Privacy Test Servers`_ supporting DNS-over-TLS to test your configuration.
Read more on :ref:`tls-forwarding`.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Forwarding to multiple targets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
With the use of slice function, it is possible to split the
.. With the use of :any:`policy.slice` function, it is possible to split the
entire DNS namespace into distinct "slices". When used in conjunction with
:ref:`TLS forwarding <tls-forwarding>`, it's possible to forward different queries to different
.. :ref:`policy.TLS_FORWARD <tls-forwarding>`, it's possible to forward different queries to different
remote resolvers. As a result no single remote resolver will get complete list
of all queries performed by this client.
.. warning::
Beware that this method has not been scientifically tested and there might be
types of attacks which will allow remote resolvers to infer more information about the client.
Again: If possible encrypt **all** your traffic and not just DNS queries!
