Daemon

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.

$ man kresd.systemd  # Help for systemd integration configuration
$ systemctl start kresd@1.service

Configuration

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.

Configuration example

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

Tip

There are more configuration examples in etc/ directory for personal, ISP, company internal and resolver cluster use cases.

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

modules = {
   'hints  > iterate', -- Hints AFTER iterate
   'policy > hints',   -- Policy AFTER hints
   'view   < cache'    -- View BEFORE cache
}
modules.list() -- Check module call order

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.

Dynamic configuration

Knowing that the the configuration is a Lua in disguise enables you to write dynamic rules. It also helps you to avoid repetitive templating that is unavoidable with static configuration.

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

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:

addrpref = env.EXPECTED_ADDR_PREFIX
for k, v in pairs(addr_list["addr"]) do
        if string.sub(v,1,string.len(addrpref)) == addrpref then
                net.listen(v)
...

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')

local cache_size = 100*MB
local cache_path = '/var/cache/knot-resolver'
cache.open(cache_size, 'lmdb://' .. cache_path)
if cache.count() == 0 then
        cache.close()
        -- download cache from parent
        http.request {
                url = 'http://parent/data.mdb',
                sink = ltn12.sink.file(io.open(cache_path .. '/data.mdb', 'w'))
        }
        -- reopen cache with 100M limit
        cache.open(cache_size, 'lmdb://' .. cache_path)
end

Asynchronous events

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.

modules.load('stats')

-- log statistics every second
local stat_id = event.recurrent(1 * second, function(evid)
    log(table_print(stats.list()))
end)

-- stop printing statistics after first minute
event.after(1 * minute, function(evid)
        event.cancel(stat_id)
end)

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 counter
function speed_monitor()
        local previous = stats.list()
        -- monitoring function
        return function(evid)
                local now = stats.list()
                local total_increment = now['answer.total'] - previous['answer.total']
                local slow_increment = now['answer.slow'] - previous['answer.slow']
                if slow_increment / total_increment > 0.05 then
                        log('WARNING! More than 5 %% of queries was slow!')
                end
                previous = now  -- store current value in closure
         end
end

-- monitor every minute
local monitor_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()

File watchers are possible with worker.coroutine() and cqueues, see the cqueues documentation for more information.

local notify = require('cqueues.notify')
local watcher = notify.opendir('/etc')
watcher:add('hosts')

-- Watch changes to /etc/hosts
worker.coroutine(function ()
  for flags, name in watcher:changes() do
    for flag in notify.flags(flags) do
      print(name, notify[flag])
    end
  end
end)

Configuration reference

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

Environment

env (table)

Return environment variable.

env.USER -- equivalent to $USER in shell
hostname([fqdn])
Returns:Machine hostname.

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.

This affects ephemeral certificates for kresd serving DNS over TLS.

verbose(true | false)
Returns:Toggle verbose logging.
mode('strict' | 'normal' | ‘permissive’)
Returns:Change resolver strictness checking level.

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.

Glue type Modes when it is accepted Example glue [1]
mandatory glue strict, normal, permissive ns1.example.org
in-bailiwick glue normal, permissive ns1.example2.org
any glue records permissive ns1.example3.net
[1]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.
reorder_RR([true | false])
Parameters:
  • value (boolean) – New value for the option (optional)
Returns:

The (new) value of the option

If set, resolver will vary the order of resource records within RR-sets. It is disabled by default.

user(name, [group])
Parameters:
  • name (string) – user name
  • group (string) – group name (optional)
Returns:

boolean

Drop privileges and run as given user (and group, if provided).

Tip

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:

-- privileged
net = { '127.0.0.1', '::1' }
-- unprivileged
cache.size = 100*MB
trust_anchors.add_file('root.key')

Example output:

> user('baduser')
invalid user name
> user('knot-resolver', 'netgrp')
true
> user('root')
Operation not permitted
resolve(name, type[, class = kres.class.IN, options = {}, finish = nil, init = nil])
Parameters:
  • name (string) – Query name (e.g. ‘com.’)
  • type (number) – Query type (e.g. kres.type.NS)
  • class (number) – Query class (optional) (e.g. kres.class.IN)
  • options (strings) – Resolution options (see kr_qflags)
  • finish (function) – Callback to be executed when resolution completes (e.g. function cb (pkt, req) end). The callback gets a packet containing the final answer and doesn’t have to return anything.
  • init (function) – Callback to be executed with the kr_request before resolution starts.
Returns:

boolean

The function can also be executed with a table of arguments instead. This is useful if you’d like to skip some arguments, for example:

resolve {
   name = 'example.com',
   type = kres.type.AAAA,
   init = function (req)
   end,
}

Example:

-- Send query for root DNSKEY, ignore cache
resolve('.', kres.type.DNSKEY, kres.class.IN, 'NO_CACHE')

-- Query for AAAA record
resolve('example.com', kres.type.AAAA, kres.class.IN, 0,
function (pkt, req)
   -- Check answer RCODE
   if pkt:rcode() == kres.rcode.NOERROR then
      -- Print matching records
      local records = pkt:section(kres.section.ANSWER)
      for i = 1, #records do
         local rr = records[i]
         if rr.type == kres.type.AAAA then
            print ('record:', kres.rr2str(rr))
         end
      end
   else
      print ('rcode: ', pkt:rcode())
   end
end)
package_version()
Returns:Current package version.

This returns current package version (the version of the binary) as a string.

> package_version()
2.1.1

Network configuration

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.

Network protocol Socket file name
DNS (UDP+TCP, RFC 1034) kresd.socket
DNS-over-TLS (DoT) kresd-tls.socket
DNS-over-HTTP (DoH) kresd-doh.socket
Web management kresd-webmgmt.socket

Warning

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:

$ systemctl edit kresd.socket
# /etc/systemd/system/kresd.socket.d/override.conf
# always listen on UDP (datagram) and TCP (stream) as well
[Socket]
ListenDatagram=192.0.2.115:53
ListenStream=192.0.2.115:53

Note

If you change network interfaces of systemd sockets for already running kresd instance, make sure to call systemctl restart system-kresd.slice for these changes to take effect.

Configuration you provide is automatically merged with defaults from your distribution. It is also possible to check resulting configuration using systemctl cat:

$ systemctl cat kresd.socket
# merged result: user configuration + distro defaults
[Socket]
FileDescriptorName=dns
FreeBind=true
BindIPv6Only=both
ListenDatagram=[::1]:53
ListenStream=[::1]:53
ListenDatagram=127.0.0.1:53
ListenStream=127.0.0.1:53
ListenDatagram=192.0.2.115:53
ListenStream=192.0.2.115:53

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`` ).

# /etc/systemd/system/kresd.socket.d/override.conf
[Socket]
ListenDatagram=
ListenStream=
ListenDatagram=53
ListenStream=53

Note

Using IPv6 to bind to IPv4 interfaces is currently not compatible with IPv4 syntax in view:addr() when using the view module. For possible workarounds, see https://gitlab.labs.nic.cz/knot/knot-resolver/issues/445

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:

# /etc/systemd/system/kresd.socket.d/override.conf
[Socket]
ListenDatagram=
ListenStream=
ListenDatagram=127.0.0.1:53000
ListenStream=127.0.0.1:53000
ListenDatagram=[::1]:53000
ListenStream=[::1]:53000

The kresd-tls.socket can also be configured in the same way to listen for DNS-over-TLS connections (RFC 7858).

$ systemctl edit kresd-tls.socket
# /etc/systemd/system/kresd-tls.socket.d/override.conf
# specify only TCP (stream), DTLS is not supported
[Socket]
ListenStream=192.0.2.115:853

When configuring sockets for DNS-over-HTTP (DoH), make sure you have kresd-doh.socket installed, it might be part of a separate knot-resolver-module-http package.

Warning

Make sure you read section DNS-over-HTTP (DoH) before exposing the DoH protocol to outside.

For example, to remove the default localhost:44353 and listen on all interfaces on port 443, create the following drop-in file for kresd-doh.socket:

$ systemctl edit kresd-doh.socket
# /etc/systemd/system/kresd-doh.socket.d/override.conf
[Socket]
ListenStream=
ListenStream=443

Make sure no other service is using port 443, as that will result in unpredictable behaviour. Alternately, you can use port 44353 where a collision is unlikely.

Also, don’t forget to load http module in configuration file, otherwise the socket won’t work.

Legacy network configuration using configuration file

If you don’t use systemd with sockets to run kresd, addresses and ports to listen on are configured in the config file.

net.listen(addresses, [port = 53, { kind = 'dns' }])
Returns:boolean

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.

Network protocol Configuration command
DNS (UDP+TCP, RFC 1034) net.listen('192.0.2.123', 53)
DNS-over-TLS (DoT) net.listen('192.0.2.123', 853, { kind = 'tls' })
DNS-over-HTTP (DoH) net.listen('192.0.2.123', 443, { kind = 'doh' })
Web management net.listen('192.0.2.123', 8453, { kind = 'webmgmt' })

Examples:

net.listen('::1')
net.listen(net.lo, 53)
net.listen(net.eth0, 853, { kind = 'tls' })
net.listen('::', 443, { kind = 'doh' }) -- see http module
net.listen('::', 8453, { kind = 'webmgmt' }) -- see http module
net.listen('/tmp/kresd-socket', nil, { kind = 'webmgmt' }) -- http module supports AF_UNIX

Warning

Make sure you read section DNS-over-HTTP (DoH) before exposing the DNS-over-HTTP protocol to outside.

net.close(address, [port])
Returns:boolean (at least one endpoint closed)

Close all endpoints listening on the specified address, optionally restricted by port as well.

Additional network configuration options

Following commands are useful in special situations and can be usef with and without systemd socket activation:

net.ipv6 = true|false
Return:boolean (default: true)

Enable/disable using IPv6 for contacting upstream nameservers.

net.ipv4 = true|false
Return:boolean (default: true)

Enable/disable using IPv4 for contacting upstream nameservers.

net.list()
Returns:Table of bound interfaces.

Example output:

[1] => {
    [kind] => tls
    [transport] => {
        [family] => inet4
        [ip] => 127.0.0.1
        [port] => 853
        [protocol] => tcp
    }
}
[2] => {
    [kind] => dns
    [transport] => {
        [family] => inet6
        [ip] => ::1
        [port] => 53
        [protocol] => udp
    }
}
[3] => {
    [kind] => dns
    [transport] => {
        [family] => inet6
        [ip] => ::1
        [port] => 53
        [protocol] => tcp
    }
}
net.interfaces()
Returns:Table of available interfaces and their addresses.

Example output:

[lo0] => {
    [addr] => {
        [1] => ::1
        [2] => 127.0.0.1
    }
    [mac] => 00:00:00:00:00:00
}
[eth0] => {
    [addr] => {
        [1] => 192.168.0.1
    }
    [mac] => de:ad:be:ef:aa:bb
}

Tip

You can use net.<iface> as a shortcut for specific interface, e.g. net.eth0

net.bufsize([udp_bufsize])

Get/set maximum EDNS payload size advertised in DNS packets. Default is 4096 bytes and the default will be lowered to value around 1220 bytes in future, once DNS Flag Day 2020 becomes effective.

Minimal value allowed by standard RFC 6891 is 512 bytes, which is equal to DNS packet size without Extension Mechanisms for DNS. Value 1220 bytes is minimum size required in DNSSEC standard RFC 4035.

Example output:

> net.bufsize(4096)
nil
> net.bufsize()
4096
net.tcp_pipeline([len])

Get/set per-client TCP pipeline limit, i.e. the number of outstanding queries that a single client connection can make in parallel. Default is 100.

> net.tcp_pipeline()
100
> net.tcp_pipeline(50)
50

Warning

Please note that too large limit may have negative impact on performance and can lead to increased number of SERVFAIL answers.

net.outgoing_v4([string address])

Get/set the IPv4 address used to perform queries. There is also net.outgoing_v6 for IPv6. The default is nil, which lets the OS choose any address.

TLS server configuration

DNS-over-TLS server (RFC 7858) is enabled by default on loopback interface port 853. Information how to configure listening on specific IP addresses is in previous sections Network configuration.

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().

net.tls([cert_path], [key_path])

Get/set path to a server TLS certificate and private key for DNS/TLS.

Example output:

> net.tls("/etc/knot-resolver/server-cert.pem", "/etc/knot-resolver/server-key.pem")
> net.tls()  -- print configured paths
("/etc/knot-resolver/server-cert.pem", "/etc/knot-resolver/server-key.pem")
net.tls_padding([true | false])

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.

net.tls_sticket_secret([string with pre-shared secret])

Set secret for TLS session resumption via tickets, by RFC 5077.

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 same as net.tls_sticket_secret(), except the secret is read from a (binary) file.

Trust anchors and DNSSEC

Since version 4.0, DNSSEC validation is enabled by default. This is secure default and should not be changed unless absolutely necessary.

Options in this section are intended only for expert users and normally should not be needed.

If you really need to turn DNSSEC off and are okay with lowering security of your system by doing so, add the following snippet to your configuration file.

-- turns off DNSSEC validation
trust_anchors.remove('.')

The resolver supports DNSSEC including RFC 5011 automated DNSSEC TA updates and RFC 7646 negative trust anchors. Depending on your distribution, DNSSEC trust anchors should be either maintained in accordance with the distro-wide policy, or automatically maintained by the resolver itself.

In practice this means that you can forget about it and your favorite Linux distribution will take care of it for you.

trust_anchors.add_file(keyfile[, readonly = false])
Parameters:
  • keyfile (string) – path to the file.
  • readonly – if true, do not attempt to update the file.

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

Example output:

> trust_anchors.add_file('root.key')
[ ta ] new state of trust anchors for a domain:
.                       165488  DS      19036 8 2 49AAC11D7B6F6446702E54A1607371607A1A41855200FD2CE1CDDE32F24E8FB5
nil

[ ta ] key: 19036 state: Valid
trust_anchors.remove(zonename)

Remove specified trust anchor from trusted key set. Removing trust anchor for the root zone effectivelly disables DNSSEC validation (unless you configured another trust anchor).

> trust_anchors.remove('.')
true

If you want to disable DNSSEC validation for a particular domain but keep it enabled for the rest of DNS tree, use trust_anchors.set_insecure().

trust_anchors.hold_down_time = 30 * day
Return:int (default: 30 * day)

Modify RFC5011 hold-down timer to given value. Intended only for testing purposes. Example: 30 * sec

trust_anchors.refresh_time = nil
Return:int (default: nil)

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

trust_anchors.keep_removed = 0
Return:int (default: 0)

How many Removed keys should be held in history (and key file) before being purged. Note: all Removed keys will be purged from key file after restarting the process.

trust_anchors.set_insecure(nta_set)
Parameters:
  • nta_list (table) – List of domain names (text format) representing NTAs.

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.

Example output:

> trust_anchors.set_insecure({ 'bad.boy', 'example.com' })
> trust_anchors.insecure
[1] => bad.boy
[2] => example.com

Warning

If you set NTA on a name that is not a zone cut, it may not always affect names not separated from the NTA by a zone cut.

trust_anchors.add(rr_string)
Parameters:
  • rr_string (string) – DS/DNSKEY records in presentation format (e.g. . 3600 IN DS 19036 8 2 49AAC11...)

Inserts DS/DNSKEY record(s) into current keyset. These will not be managed or updated, use it only for testing or if you have a specific use case for not using a keyfile.

Note

Static keys are very error-prone and should not be used in production. Use trust_anchors.add_file() instead.

Example output:

> trust_anchors.add('. 3600 IN DS 19036 8 2 49AAC11...')
trust_anchors.summary()

Return string with summary of configured DNSSEC trust anchors, including negative TAs.

Modules configuration

The daemon provides an interface for dynamic loading of daemon modules.

Tip

Use declarative interface for module loading.

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

Equals to:

modules.load('hints')
hints.config({file = '/etc/hosts'})
modules.list()
Returns:List of loaded modules.
modules.load(name)
Parameters:
  • name (string) – Module name, e.g. “hints”
Returns:

boolean

Load a module by name.

modules.unload(name)
Parameters:
  • name (string) – Module name
Returns:

boolean

Unload a module by name.

Cache configuration

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.

cache.open(max_size[, config_uri])
Parameters:
  • max_size (number) – Maximum cache size in bytes.
Returns:

true if cache was opened

Open cache with a size limit. The cache will be reopened if already open. Note that the max_size cannot be lowered, only increased due to how cache is implemented.

Tip

Use kB, MB, GB constants as a multiplier, e.g. 100*MB.

As of now, the built-in backend with URI lmdb:// allows you to change the cache directory.

Example:

cache.open(100 * MB, 'lmdb:///var/cache/knot-resolver')
cache.size

Set the cache maximum size in bytes. Note that this is only a hint to the backend, which may or may not respect it. See cache.open().

cache.size = 100 * MB -- equivalent to `cache.open(100 * MB)`
cache.current_size

Get the maximum size in bytes.

print(cache.current_size)
cache.storage

Set the cache storage backend configuration, see cache.backends() for more information. If the new storage configuration is invalid, it is not set.

cache.storage = 'lmdb://.'
cache.current_storage

Get the storage backend configuration.

print(cache.current_storage)
cache.backends()
Returns:map of backends

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://.

Example output:

[lmdb://] => true
cache.count()
Returns:Number of entries in the cache. Meaning of the number is an implementation detail and is subject of change.
cache.close()
Returns:true if cache was closed

Close the cache.

Note

This may or may not clear the cache, depending on the cache backend.

cache.stats()

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.

Example:

> cache.stats()
[read_leq_miss] => 4
[write] => 189
[read_leq] => 9
[read] => 4313
[read_miss] => 1143
[open] => 0
[close] => 0
[remove_miss] => 0
[commit] => 117
[match_miss] => 2
[match] => 21
[count] => 2
[clear] => 0
[remove] => 17

Cache operation read_leq (read less or equal, i.e. range search) was requested 9 times, and 4 out of 9 operations were finished with cache miss.

cache.max_ttl([ttl])
Parameters:
  • ttl (number) – maximum cache TTL in seconds (default: 6 days)
Returns:current maximum TTL

Get or set maximum cache TTL.

Note

The ttl value must be in range (min_ttl, 4294967295).

Warning

This settings applies only to currently open cache, it will not persist if the cache is closed or reopened.

-- Get maximum TTL
cache.max_ttl()
518400
-- Set maximum TTL
cache.max_ttl(172800)
172800
cache.min_ttl([ttl])
Parameters:
  • ttl (number) – minimum cache TTL in seconds (default: 5 seconds)
Returns:current maximum TTL

Get or set minimum cache TTL. Any entry inserted into cache with TTL lower than minimal will be overridden to minimum TTL. Forcing TTL higher than specified violates DNS standards, use with care.

Note

The ttl value must be in range <0, max_ttl).

Warning

This settings applies only to currently open cache, it will not persist if the cache is closed or reopened.

-- Get minimum TTL
cache.min_ttl()
0
-- Set minimum TTL
cache.min_ttl(5)
5
cache.ns_tout([timeout])
Parameters:
Returns:

current timeout

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

Warning

This settings applies only to the current kresd process.

cache.get([domain])

This function is not implemented at this moment. We plan to re-introduce it soon, probably with a slightly different API.

cache.clear([name], [exact_name], [rr_type], [chunk_size], [callback], [prev_state])

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

Examples:

-- Clear whole cache
> cache.clear()
[count] => 76

-- Clear records at and below 'com.'
> cache.clear('com.')
[chunk_limit] => chunk size limit reached; the default callback will continue asynchronously
[not_apex] => to clear proofs of non-existence call cache.clear('com.')
[count] => 100
[round] => 1
[subtree] => com.
> worker.sleep(0.1)
[cache] asynchonous cache.clear('com', false) finished

-- Clear only 'www.example.com.'
> cache.clear('www.example.com.', true)
[round] => 1
[count] => 1
[not_apex] => to clear proofs of non-existence call cache.clear('example.com.')
[subtree] => example.com.
[2]This is a consequence of DNSSEC negative cache which relies on proofs of non-existence on various owner nodes. It is impossible to efficiently flush part of DNS zones signed with NSEC3.

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.

event.after(time, function)
Returns:event id

Execute function after the specified time has passed. The first parameter of the callback is the event itself.

Example:

event.after(1 * minute, function() print('Hi!') end)
event.recurrent(interval, function)
Returns:event id

Similar to event.after(), periodically execute function after interval passes.

Example:

msg_count = 0
event.recurrent(5 * sec, function(e)
   msg_count = msg_count + 1
   print('Hi #'..msg_count)
end)
event.reschedule(event_id, timeout)

Reschedule a running event, it has no effect on canceled events. New events may reuse the event_id, so the behaviour is undefined if the function is called after another event is started.

Example:

local interval = 1 * minute
event.after(1 * minute, function (ev)
   print('Good morning!')
   -- Halven the interval for each iteration
   interval = interval / 2
   event.reschedule(ev, interval)
end)
event.cancel(event_id)

Cancel running event, it has no effect on already canceled events. New events may reuse the event_id, so the behaviour is undefined if the function is called after another event is started.

Example:

e = event.after(1 * minute, function() print('Hi!') end)
event.cancel(e)

Watch for file descriptor activity. This allows embedding other event loops or simply firing events when a pipe endpoint becomes active. In another words, asynchronous notifications for daemon.

event.socket(fd, cb)
Parameters:
  • fd (number) – file descriptor to watch
  • cb – closure or callback to execute when fd becomes active
Returns:

event id

Execute function when there is activity on the file descriptor and calls a closure with event id as the first parameter, status as second and number of events as third.

Example:

e = event.socket(0, function(e, status, nevents)
   print('activity detected')
end)
e.cancel(e)

Asynchronous function execution

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

worker.coroutine(function)

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.

Example:

worker.coroutine(function ()
  for i = 0, 10 do
    print('executing', i)
    worker.sleep(1)
  end
end)
worker.sleep(seconds)

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.

Example:

worker.sleep(1)
map(expr)

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 only
hostname()
localhost
-- Mapped to forks
map 'hostname()'
[1] => localhost
[2] => localhost
-- Get worker ID from each fork
map 'worker.id'
[1] => 0
[2] => 1
-- Get cache stats from each fork
map 'cache.stats()'
[1] => {
    [hit] => 0
    [delete] => 0
    [miss] => 0
    [insert] => 0
}
[2] => {
    [hit] => 0
    [delete] => 0
    [miss] => 0
    [insert] => 0
}

Scripting worker

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.

worker.count

Return current total worker count (e.g. 1 for single-process)

worker.id

Return current worker ID (starting from 0 up to worker.count - 1)

worker.pid

Current worker process PID (number).

worker.stats()

Return table of statistics. See member descriptions in worker_stats. A few fields are added, mainly from POSIX getrusage():

  • usertime and systime – CPU time used, in seconds
  • pagefaults – the number of hard page faults, i.e. those that required I/O activity
  • swaps – the number of times the process was “swapped” out of main memory; unused on Linux
  • csw – the number of context switches, both voluntary and involuntary
  • rss – current memory usage in bytes, including whole cache (resident set size)

Example:

print(worker.stats().concurrent)

CLI interface

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

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

Verbose output

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 -f 1 to start a single fork. For example:

$ nohup ./daemon/kresd -a 127.0.0.1 -f 1 -v &

Control sockets

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 systemctl status kresd-control@*.socket. Typically, these are in /run/knot-resolver/control@*.

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

Utilizing multiple CPUs

The server can run in multiple independent processes, all sharing the same socket and cache. These processes can be started or stopped during runtime based on the load.

Using systemd

To run multiple daemons using systemd, use a different numeric identifier for the instance, for example:

$ systemctl start kresd@1.service
$ systemctl start kresd@2.service
$ systemctl start kresd@3.service
$ systemctl start kresd@4.service

With the use of brace expansion, the equivalent command looks like:

$ systemctl start kresd@{1..4}.service

For more details, see kresd.systemd(7).

Daemon only

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

Note

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.

Cache Garbage Collector

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:

$ kres-cache-gc -c /var/cache/knot-resolver -d 1000

Using CLI tools

  • kresd-host.lua - a drop-in replacement for host(1) utility

Queries the DNS for information. The hostname is looked up for IP4, IP6 and mail.

Example:

$ kresd-host.lua -f root.key -v nic.cz
nic.cz. has address 217.31.205.50 (secure)
nic.cz. has IPv6 address 2001:1488:0:3::2 (secure)
nic.cz. mail is handled by 10 mail.nic.cz. (secure)
nic.cz. mail is handled by 20 mx.nic.cz. (secure)
nic.cz. mail is handled by 30 bh.nic.cz. (secure)
  • kresd-query.lua - run the daemon in zero-configuration mode, perform a query and execute given callback.

This is useful for executing one-shot queries and hooking into the processing of the result, for example to check if a domain is managed by a certain registrar or if it’s signed.

Example:

$ kresd-query.lua www.sub.nic.cz 'assert(kres.dname2str(req:resolved().zone_cut.name) == "nic.cz.")' && echo "yes"
yes
$ kresd-query.lua -C 'trust_anchors.add_file("root.keys")' nic.cz 'assert(req:resolved().flags.DNSSEC_WANT)'
$ echo $?
0

Code reference

Functions

int worker_init(struct engine * engine, int worker_id, int worker_count)

Create and initialize the worker.

Return
error code (ENOMEM)

void worker_deinit(void)

Destroy the worker (free memory).

int worker_submit(struct session * session, knot_pkt_t * query)

Process an incoming packet (query from a client or answer from upstream).

Return
0 or an error code
Parameters
  • session: session the where packet came from
  • query: the packet, or NULL on an error from the transport layer

int worker_end_tcp(struct session * session)

End current DNS/TCP session, this disassociates pending tasks from this session which may be freely closed afterwards.

KR_EXPORT knot_pkt_t* worker_resolve_mk_pkt(const char * qname_str, uint16_t qtype, uint16_t qclass, const struct kr_qflags * options)

Create a packet suitable for worker_resolve_start().

All in malloc() memory.

KR_EXPORT struct qr_task* worker_resolve_start(knot_pkt_t * query, struct kr_qflags options)

Start query resolution with given query.

Return
task or NULL

KR_EXPORT int worker_resolve_exec(struct qr_task * task, knot_pkt_t * query)
struct kr_request* worker_task_request(struct qr_task * task)

Return
struct kr_request associated with opaque task

int worker_task_step(struct qr_task * task, const struct sockaddr * packet_source, knot_pkt_t * packet)
int worker_task_numrefs(const struct qr_task * task)
int worker_task_finalize(struct qr_task * task, int state)

Finalize given task.

void worker_task_complete(struct qr_task * task)
void worker_task_ref(struct qr_task * task)
void worker_task_unref(struct qr_task * task)
void worker_task_timeout_inc(struct qr_task * task)
int worker_add_tcp_connected(struct worker_ctx * worker, const struct sockaddr * addr, struct session * session)
int worker_del_tcp_connected(struct worker_ctx * worker, const struct sockaddr * addr)
int worker_del_tcp_waiting(struct worker_ctx * worker, const struct sockaddr * addr)
knot_pkt_t* worker_task_get_pktbuf(const struct qr_task * task)
struct request_ctx* worker_task_get_request(struct qr_task * task)
struct session* worker_request_get_source_session(struct request_ctx *)
void worker_request_set_source_session(struct request_ctx *, struct session * session)
uint16_t worker_task_pkt_get_msgid(struct qr_task * task)
void worker_task_pkt_set_msgid(struct qr_task * task, uint16_t msgid)
uint64_t worker_task_creation_time(struct qr_task * task)
void worker_task_subreq_finalize(struct qr_task * task)
bool worker_task_finished(struct qr_task * task)
int qr_task_on_send(struct qr_task * task, uv_handle_t * handle, int status)

To be called after sending a DNS message.

It mainly deals with cleanups.

Variables

KR_EXPORT struct worker_ctx* the_worker

Pointer to the singleton worker.

NULL if not initialized.

struct worker_stats
#include <worker.h>

Various worker statistics.

Sync with wrk_stats()

Public Members

size_t queries

Total number of requests (from clients and internal ones).

size_t concurrent

The number of requests currently in processing.

size_t rconcurrent
size_t dropped

The number of requests dropped due to being badly formed.

See #471.

size_t timeout

Number of outbound queries that timed out.

size_t udp

Number of outbound queries over UDP.

size_t tcp

Number of outbound queries over TCP (excluding TLS).

size_t tls

Number of outbound queries over TLS.

size_t ipv4

Number of outbound queries over IPv4.

size_t ipv6

Number of outbound queries over IPv6.