Configuration

Easiest way to configure Knot Resolver is to put YAML configuration in /etc/knot-resolver/config.yaml file.

You can start exploring the configuration by continuing in this chapter or look at the complete configuration documentation.

Complete examples of configuration files can be found here. 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 kresctl utility to validate your configuration before pushing it into the running resolver. It should help prevent many typos in the configuration.

$ kresctl validate /etc/knot-resolver/config.yaml

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.

$ 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.

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. Encrypted DNS queries using DNS-over-TLS protocol are accepted on all IP addresses of eth0 network interface, TCP port 853.

network:
    listen:
    - interface: ['192.0.2.1', '2001:db8::1'] # port 53 is default
    - interface: 'eth0'
        port: 853
        kind: 'dot' # DNS-over-TLS

For more details look at the network configuration.

Warning

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.

Example: Internal Resolver

This is an example of typical configuration for company-internal resolver which is not accessible from outside of company network.

Internal-only domains

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.

policy:

See chapter Replacing part of the DNS tree for more details.

Example: ISP Resolver

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.

Limiting client access

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.

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 policy rules. Following configuration allows only queries from clients in subnet 192.0.2.0/24 and refuses all the rest.

view:

policy:

TLS server configuration

Today clients are demanding secure transport for DNS queries between client machine and DNS resolver. The recommended way to achieve this is to start DNS-over-TLS server and accept also encrypted queries.

First step is to enable TLS on listening interfaces:

network:
    listen:
    - interface: ['192.0.2.1', '2001:db8::1']
        kind: 'dot' # DNS-over-TLS, port 853 is default

By default a self-signed certificate is generated. Second step is then obtaining and configuring your own TLS certificates signed by a trusted CA. Once the certificate was obtained a path to certificate files can be specified:

network:
    tls:
        cert-file: '/etc/knot-resolver/server-cert.pem'
        key-file: '/etc/knot-resolver/server-key.pem'

Mandatory domain blocking

Some jurisdictions mandate blocking access to certain domains. This can be achieved using following policy rule:

policy:

Example: Personal Resolver

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:

Forwarding over TLS protocol (DNS-over-TLS)

Forwarding over TLS protocol protects DNS queries sent out by resolver. It can be configured using TLS forwarding which provides methods for authentication. .. It can be configured using policy.TLS_FORWARD which provides methods for authentication. See list of DNS Privacy Test Servers supporting DNS-over-TLS to test your configuration.

Read more on Forwarding over TLS protocol (DNS-over-TLS).

Forwarding to multiple targets

With the use of slice function, it is possible to split the .. With the use of policy.slice function, it is possible to split the entire DNS namespace into distinct “slices”. When used in conjunction with TLS forwarding, it’s possible to forward different queries to different .. policy.TLS_FORWARD, 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!

policy:
    # TODO

Non-persistent cache

Knot Resolver’s cache contains data clients queried for. If you are concerned about attackers who are able to get access to your computer system in power-off state and your storage device is not secured by encryption you can move the cache to tmpfs. See chapter Persistence.