The server is in the daemon directory, it works out of the box without any configuration.

$ kresd -v # run with defaults in verbose mode
$ kresd -h # Get help

If you’re using our packages, they also provide systemd integration. To start the resolver under systemd, you can use the kresd@1.service service. By default, the resolver only binds to local interfaces.

In its simplest form the server requires just a working directory in which it can set up persistent files like
cache and the process state. If you don’t provide the working directory by parameter, it is going to make itself
comfortable in the current working directory.

$ kresd /var/cache/knot-resolver

And you’re good to go for most use cases! If you want to use modules or configure daemon behavior, read on.

There are several choices on how you can configure the daemon, a RPC interface, a CLI, and a configuration file.
Fortunately all share common syntax and are transparent to each other.

The configuration is kept in the config file in the daemon working directory, and it’s going to get loaded automatically.
If there isn’t one, the daemon is going to start with sane defaults, listening on localhost.
The syntax for options is like follows: group.option=value or group.action(parameters).
You can also comment using a -- prefix.

A simple example would be to load static hints.

modules={'hints'-- no configuration}

If the module accepts configuration, you can call the module.config({...}) or provide options table.
The syntax for table is {key1=value,key2=value}, and it represents the unpacked JSON-encoded string, that
the modules use as the input configuration.

modules={hints='/etc/hosts'}

Warning

Modules specified including their configuration may not load exactly in the same order as specified.

Modules are inherently ordered by their declaration. Some modules are built-in, so it would be normally impossible to place for example hints before cache. You can enforce specific order by precedence operators > and <.

This is useful if you’re writing a module with a layer, that evaluates an answer before writing it into cache for example.

Tip

The configuration and CLI syntax is Lua language, with which you may already be familiar with.
If not, you can read the Learn Lua in 15 minutes for a syntax overview. Spending just a few minutes
will allow you to break from static configuration, write more efficient configuration with iteration, and
leverage events and hooks. Lua is heavily used for scripting in applications ranging from embedded to game engines,
but in DNS world notably in PowerDNS Recursor. Knot Resolver does not simply use Lua modules, but it is
the heart of the daemon for everything from configuration, internal events and user interaction.

Another example would show how it is possible to bind to all interfaces, using iteration.

forname,addr_listinpairs(net.interfaces())donet.listen(addr_list)end

Tip

Some users observed a considerable, close to 100%, performance gain in Docker containers when they bound the daemon to a single interface:ip address pair. One may expand the aforementioned example with browsing available addresses as:

Lua supports a concept called closures, this is extremely useful for scripting actions upon various events,
say for example - publish statistics each minute and so on.
Here’s an example of an anonymous function with event.recurrent().

Note that each scheduled event is identified by a number valid for the duration of the event,
you may use it to cancel the event at any time.

If you need to persist state between events, encapsulate even handle in closure function which will provide persistent variable (called previous):

modules.load('stats')-- make a closure, encapsulating counterfunctionspeed_monitor()localprevious=stats.list()-- monitoring functionreturnfunction(evid)localnow=stats.list()localtotal_increment=now['answer.total']-previous['answer.total']localslow_increment=now['answer.slow']-previous['answer.slow']ifslow_increment/total_increment>0.05thenlog('WARNING! More than 5 %% of queries was slow!')endprevious=now-- store current value in closureendend-- monitor every minutelocalmonitor_id=event.recurrent(1*minute,speed_monitor())

Another type of actionable event is activity on a file descriptor. This allows you to embed other
event loops or monitor open files and then fire a callback when an activity is detected.
This allows you to build persistent services like HTTP servers or monitoring probes that cooperate
well with the daemon internal operations. See event.socket()

If called with a parameter, it will set kresd’s internal
hostname. If called without a parameter, it will return kresd’s
internal hostname, or the system’s POSIX hostname (see
gethostname(2)) if kresd’s internal hostname is unset.

By default, resolver runs in normal mode. There are possibly many small adjustments
hidden behind the mode settings, but the main idea is that in permissive mode, the resolver
tries to resolve a name with as few lookups as possible, while in strict mode it spends much
more effort resolving and checking referral path. However, if majority of the traffic is covered
by DNSSEC, some of the strict checking actions are counter-productive.

The examples show glue records acceptable from servers
authoritative for org zone when delegating to example.org zone.
Unacceptable or missing glue records trigger resolution of names listed
in NS records before following respective delegation.

Note that you should bind to required network addresses before changing user. At the same time, you should open the cache AFTER you change the user (so it remains accessible). A good practice is to divide configuration in two parts:

Modern Linux distributions use so-called Systemd socket activation, which
effectively means that IP addresses and ports to listen on are configured
in Systemd configuration files.

Older Linux systems and all non-Linux systems do not support this modern method
and have to resort to old fashioned way of configuring network interfaces using
net.listen() configuration call.
Most notable examples of such systems are CentOS 7 and macOS.

Warning

On machines with multiple IP addresses 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 probably refuse such a response.

Network configuration using systemd

If you’re using our packages with systemd with sockets support (not supported
on CentOS 7), network interfaces are configured using systemd drop-in files.

Each protocol has its own configuration file. By default, these are configured
to listen on localhost.

You MUST NOT repeat the localhost defaults in the following
drop-in overrides, otherwise the socket will fail to start with “Address in
use” error. To view the entire socket configuration, including any drop-ins,
use systemctl cat.

To configure kresd to listen on a public interface using the original DNS protocol,
create a drop-in file:

The default localhost interface/port can also be removed/overriden by using an
empty ListenDatagram= or ListenStream= directive. This can be used when
you want to configure kresd to listen on all IPv4/IPv6 network interfaces (if
you’ve disabled IPv6 support in kernel, use 0.0.0.0:port instead`` ).

It can also be useful if you want to use the Knot DNS authoritative server
with the dnsproxy module to have both resolver and authoritative server
running on the same machine. This is not recommended configuration but it can
be done like this:

Listen on addresses; port and flags are optional.
The addresses can be specified as a string or device.
The command can be given multiple times,
but repeating an address-port combination is an error.
Port 853 implies kind='tls' but it is always better to be explicit.

By default a self-signed certificate is generated. For serious deployments
it is strongly recommended to configure your own TLS certificates signed
by a trusted CA. This is done using function net.tls().

Get/set EDNS(0) padding of answers to queries that arrive over TLS
transport. If set to true (the default), it will use a sensible
default padding scheme, as implemented by libknot if available at
compile time. If set to a numeric value >= 2 it will pad the
answers to nearest padding boundary, e.g. if set to 64, the
answer will have size of a multiple of 64 (64, 128, 192, …). If
set to false (or a number < 2), it will disable padding entirely.

The server-side key is rotated roughly once per hour.
By default or if called without secret, the key is random.
That is good for long-term forward secrecy, but multiple kresd instances
won’t be able to resume each other’s sessions.

If you provide the same secret to multiple instances, they will be able to resume
each other’s sessions without any further communication between them.
This synchronization works only among instances having the same endianess
and time_t structure and size (sizeof(time_t)).

For good security the secret must have enough entropy to be hard to guess,
and it should still be occasionally rotated manually and securely forgotten,
to reduce the scope of privacy leak in case the
secret leaks eventually.

Warning

Setting the secret is probably too risky with TLS <= 1.2.
GnuTLS stable release supports TLS 1.3 since 3.6.3 (summer 2018).
Therefore setting the secrets should be considered experimental for now
and might not be available on your system.

net.tls_sticket_secret_file([string with path to a file containing pre-shared secret])¶

The format is standard zone file, though additional information may be persisted in comments.
Either DS or DNSKEY records can be used for TAs.
If the file does not exist, bootstrapping of root TA will be attempted.

Each file can only contain records for a single domain.
The TAs will be updated according to RFC 5011 and persisted in the file (if allowed).

Modify RFC5011 refresh timer to given value (not set by default), this will force trust anchors
to be updated every N seconds periodically instead of relying on RFC5011 logic and TTLs.
Intended only for testing purposes.
Example: 10*sec

When you use a domain name as an negative trust anchor (NTA), DNSSEC validation will be turned off at/below these names.
Each function call replaces the previous NTA set. You can find the current active set in trust_anchors.insecure variable.
If you want to disable DNSSEC validation completely use trust_anchors.remove() function instead.

The default cache in Knot Resolver is persistent with LMDB backend, this means that the daemon doesn’t lose
the cached data on restart or crash to avoid cold-starts. The cache may be reused between cache
daemons or manipulated from other processes, making for example synchronized load-balanced recursors possible.

The cache supports runtime-changeable backends, using the optional RFC 3986 URI, where the scheme
represents backend protocol and the rest of the URI backend-specific configuration. By default, it
is a lmdb backend in working directory, i.e. lmdb://.

Return table with low-level statistics for each internal cache operation.
This counts each access to cache and does not directly map to individual
DNS queries or resource records.
For query-level statistics see stats module.

Get or set time interval for which a nameserver address will be ignored after determining that it doesn’t return (useful) answers.
The intention is to avoid waiting if there’s little hope; instead, kresd can immediately SERVFAIL or immediately use stale records (with serve_stale module).

Purge cache records matching specified criteria. There are two specifics:

To reliably remove negative cache entries you need to clear subtree with the whole zone. E.g. to clear negative cache entries for (formerly non-existing) record www.example.com. A you need to flush whole subtree starting at zone apex, e.g. example.com.[2].

This operation is asynchronous and might not be yet finished when call to cache.clear() function returns. Return value indicates if clearing continues asynchronously or not.

Parameters:

name (string) – subtree to purge; if the name isn’t provided, whole cache is purged
(and any other parameters are disregarded).

exact_name (bool) – if set to true, only records with the same name are removed;
default: false.

rr_type (kres.type) – you may additionally specify the type to remove,
but that is only supported with exact_name==true; default: nil.

chunk_size (integer) – the number of records to remove in one round; default: 100.
The purpose is not to block the resolver for long.
The default callback repeats the command after one millisecond
until all matching data are cleared.

callback (function) – a custom code to handle result of the underlying C call.
Its parameters are copies of those passed to cache.clear() with one additional
parameter rettable containing table with return value from current call.
count field contains a return code from kr_cache_remove_subtree().

prev_state (table) – return value from previous run (can be used by callback)

Return type:

table

Returns:

count key is always present. Other keys are optional and their presence indicate special conditions.

count(integer) - number of items removed from cache by this call (can be 0 if no entry matched criteria)

not_apex - cleared subtree is not cached as zone apex; proofs of non-existence were probably not removed

subtree(string) - hint where zone apex lies (this is estimation from cache content and might not be accurate)

chunk_limit - more than chunk_size items needs to be cleared, clearing will continue asynchronously

The timer represents exactly the thing described in the examples - it allows you to execute closures
after specified time, or event recurrent events. Time is always described in milliseconds,
but there are convenient variables that you can use - sec,minute,hour.
For example, 5*hour represents five hours, or 5*60*60*100 milliseconds.

The event package provides a very basic mean for non-blocking execution - it allows running code when activity on a file descriptor is detected, and when a certain amount of time passes. It doesn’t however provide an easy to use abstraction for non-blocking I/O. This is instead exposed through the worker package (if cqueues Lua package is installed in the system).

Start a new coroutine with given function (closure). The function can do I/O or run timers without blocking the main thread. See cqueues for documentation of possible operations and synchronization primitives. The main limitation is that you can’t wait for a finish of a coroutine from processing layers, because it’s not currently possible to suspend and resume execution of processing layers.

Pause execution of current function (asynchronously if running inside a worker coroutine).

When daemon is running in forked mode, each process acts independently. This is good because it reduces software complexity and allows for runtime scaling, but not ideal because of additional operational burden.
For example, when you want to add a new policy, you’d need to add it to either put it in the configuration, or execute command on each process independently. The daemon simplifies this by promoting process group leader which is able to execute commands synchronously over forks.

Run expression synchronously over all forks, results are returned as a table ordered as forks. Expression can be any valid expression in Lua.

Example:

-- Current instance onlyhostname()localhost-- Mapped to forksmap'hostname()'[1]=>localhost[2]=>localhost-- Get worker ID from each forkmap'worker.id'[1]=>0[2]=>1-- Get cache stats from each forkmap'cache.stats()'[1]=>{[hit]=>0[delete]=>0[miss]=>0[insert]=>0}[2]=>{[hit]=>0[delete]=>0[miss]=>0[insert]=>0}

Worker is a service over event loop that tracks and schedules outstanding queries,
you can see the statistics or schedule new queries. It also contains information about
specified worker count and process rank.

If the verbose logging is compiled in, i.e. not turned off by
verbose_log=disabled, you can turn on verbose tracing of server operation
with the -v option. You can also toggle it on runtime with
verbose(true|false) command.

$ kresd -v

To run the daemon by hand, such as under nohup, use -f1 to start a single fork. For example:

Unless ran manually, knot-resolver is typically started in non-interactive mode.
The mode gets triggered by using the -f command-line parameter or by passing sockets from systemd.
You can attach to the the consoles for each process; by default they are in rundir/tty/$PID.

Note

When running kresd with systemd, you can find the location of the socket(s) using systemctlstatuskresd-control@*.socket. Typically, these are in /run/knot-resolver/control@*.

The direct output of the CLI command is captured and sent over the socket, while also printed to the daemon standard outputs (for accountability). This gives you an immediate response on the outcome of your command.
Error or debug logs aren’t captured, but you can find them in the daemon standard outputs.

This is also a way to enumerate and test running instances, the list of files in tty corresponds to the list
of running processes, and you can test the process for liveliness by connecting to the UNIX socket.

On recent Linux supporting SO_REUSEPORT (since 3.9, backported to RHEL 2.6.32) it is also able to bind to the same endpoint and distribute the load between the forked processes. If your OS doesn’t support it, use only one daemon process.

kresd daemon uses the available cache until it’s full. When more space is
required, the entire cache is dropped. To avoid starting over with an empty
cache, a separate garbage collector daemon is available to periodically trim
the cache instead.

The cache garbage collector daemon (kres-cache-gc) monitors the cache usage
and attempts to free up space when a threshold is reached. A garbage collector
systemd service, kres-cache-gc.service is turned on in our upstream packages.

To spawn the daemon manually and configure it to run every second, use: