Knot DNS Resolver daemon

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

$ kresd -h # Get help
$ kresd -a ::1

Enabling DNSSEC

The resolver supports DNSSEC including RFC 5011 automated DNSSEC TA updates and RFC 7646 negative trust anchors. To enable it, you need to provide at least _one_ trust anchor. This step is not automatic, as you're supposed to obtain the trust anchor using a secure channel. From there, the Knot DNS Resolver can perform automatic updates for you.

1. Check the current TA published on IANA website
2. Fetch current keys (DNSKEY), verify digests
3. Deploy them

$ kdig DNSKEY . @a.root-servers.net +noall +answer | grep 257 > root.keys
$ ldns-key2ds -n root.keys # Only print to stdout
... verify that digest matches TA published by IANA ...
$ kresd -k root.keys

You've just enabled DNSSEC!

CLI interface

The daemon features a CLI interface, type help to see the list of available commands.

$ kresd /var/run/knot-resolver
[system] started in interactive mode, type 'help()'
> cache.count()
53

Verbose output

If the debug logging is compiled in, 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

Scaling out

The server can clone itself into multiple processes upon startup, this enables you to scale it on multiple cores. Multiple processes can serve different addresses, but still share the same working directory and cache. You can add start and stop processes on runtime based on the load.

$ kresd -f 4 rundir > kresd.log &
$ kresd -f 2 rundir > kresd_2.log & # Extra instances
$ pstree $$ -g
bash(3533)─┬─kresd(19212)─┬─kresd(19212)
           │              ├─kresd(19212)
           │              └─kresd(19212)
           ├─kresd(19399)───kresd(19399)
           └─pstree(19411)
$ kill 19399 # Kill group 2, former will continue to run
bash(3533)─┬─kresd(19212)─┬─kresd(19212)
           │              ├─kresd(19212)
           │              └─kresd(19212)
           └─pstree(19460)

Notice the absence of an interactive CLI. You can attach to the the consoles for each process, they are in rundir/tty/PID.

$ nc -U rundir/tty/3008 # or socat - UNIX-CONNECT:rundir/tty/3008
> cache.count()
53

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 int tty correspond to list of running processes, and you can test the process for liveliness by connecting to the UNIX socket.

Configuration

In it's simplest form it 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/run/kresd

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.

Configuration example

-- 10MB cache
cache.size = 10*MB
-- load some modules
modules = { 'policy', 'cachectl' }
-- interfaces
net = { '127.0.0.1', '::1' }

Configuration syntax

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 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 :ref:`input configuration <mod-properties>`.

modules = {
        cachectl = true,
        hints = '/etc/hosts'
}

Dynamic configuration

Knowing that the the configuration is a Lua in disguise enables you to write dynamic rules, and also avoid repetition and templating. This is unavoidable with static configuration, e.g. when you want to configure each node a little bit differently.

if hostname() == 'hidden' then
        net.listen(net.eth0, 5353)
else
        net = { '127.0.0.1', net.eth1.addr[1] }
end

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

for name, addr_list in pairs(net.interfaces()) do
        net.listen(addr_list)
end

You can also use third-party packages (available for example through LuaRocks) as on this example to download cache from parent, to avoid cold-cache start.

local http = require('socket.http')
local ltn12 = require('ltn12')

if cache.count() == 0 then
        -- download cache from parent
        http.request {
                url = 'http://parent/cache.mdb',
                sink = ltn12.sink.file(io.open('cache.mdb', 'w'))
        }
        -- reopen cache with 100M limit
        cache.size = 100*MB
end

Events and services

The Lua supports a concept called closures, this is extremely useful for scripting actions upon various events, say for example - prune the cache within minute after loading, publish statistics each 5 minutes and so on. Here's an example of an anonymous function with :func:`event.recurrent()`:

-- every 5 minutes
event.recurrent(5 * minute, function()
        cachectl.prune()
end)

Note that each scheduled event is identified by a number valid for the duration of the event, you may cancel it at any time. You can do this with anonymous functions, if you accept the event as a parameter, but it's not very useful as you don't have any non-global way to keep persistent variables.

-- make a closure, encapsulating counter
function pruner()
        local i = 0
        -- pruning function
        return function(e)
                cachectl.prune()
                -- cancel event on 5th attempt
                i = i + 1
                if i == 5 then
                        event.cancel(e)
                fi
        end
end

-- make recurrent event that will cancel after 5 times
event.recurrent(5 * minute, pruner())

• File watchers
• Data I/O

Configuration reference

This is a reference for variables and functions available to both configuration file and CLI.

Environment

Network configuration

For when listening on localhost just doesn't cut it.

net = { '127.0.0.1', net.eth0, net.eth1.addr[1] }
net.ipv4 = false

Trust anchors and DNSSEC

Modules configuration

The daemon provides an interface for dynamic loading of :ref:`daemon modules <modules-implemented>`.

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

modules.load('cachectl')
modules.load('hints')
hints.config({file = '/etc/hosts'})

Cache configuration

The cache in Knot DNS 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 synchronised load-balanced recursors possible.

Timers and events

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.

Scripting worker

Worker is a service over event loop that tracks and schedules outstanding queries, you can see the statistics or schedule new queries.