Addresses and services

Addresses, ports, protocols, and API calls available for clients communicating with resolver are configured using net.listen().

First you need to decide what service should be available on given IP address + port combination.

Protocol/service

net.listen kind

DNS (unencrypted UDP+TCP, RFC 1034)

dns

DNS (unencrypted UDP, using XDP Linux API)

xdp

DNS-over-TLS (DoT)

tls

DNS-over-HTTPS (DoH)

doh2

Web management

webmgmt

Control socket

control

Legacy DNS-over-HTTPS (DoH)

doh_legacy

Note

By default, unencrypted DNS and DNS-over-TLS are configured to listen on localhost.

Control sockets are created either in /run/knot-resolver/control/ (when using systemd) or $PWD/control/.

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

true if port is bound, an error otherwise

Listen on addresses; port and flags are optional. The addresses can be specified as a string or device. Port 853 implies kind = 'tls' but it is always better to be explicit. Freebind allows binding to a non-local or not yet available address.

Network protocol

Configuration command

DNS (UDP+TCP, RFC 1034)

net.listen('192.0.2.123', 53)

DNS (UDP, using XDP)

net.listen('192.0.2.123', 53, { kind = 'xdp' })

DNS-over-TLS (DoT)

net.listen('192.0.2.123', 853, { kind = 'tls' })

DNS-over-HTTPS (DoH)

net.listen('192.0.2.123', 443, { kind = 'doh2' })

Web management

net.listen('192.0.2.123', 8453, { kind = 'webmgmt' })

Control socket

net.listen('/tmp/kres.control', nil, { kind = 'control' })

Examples:

net.listen('::1')
net.listen(net.lo, 53)
net.listen(net.eth0, 853, { kind = 'tls' })
net.listen('192.0.2.1', 53, { freebind = true })
net.listen({'127.0.0.1', '::1'}, 53, { kind = 'dns' })
net.listen('::', 443, { kind = 'doh2' })
net.listen('::', 8453, { kind = 'webmgmt' }) -- see http module
net.listen('/tmp/kresd-socket', nil, { kind = 'webmgmt' }) -- http module supports AF_UNIX
net.listen('eth0', 53, { kind = 'xdp' })
net.listen('192.0.2.123', 53, { kind = 'xdp', nic_queue = 0 })

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.

Features for scripting

Following configuration functions are useful mainly for scripting or Run-time reconfiguration.

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.

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
    }
}
[4] => {
    [kind] => xdp
    [transport] => {
        [family] => inet4+inet6
        [interface] => eth2
        [nic_queue] => 0
        [port] => 53
        [protocol] => udp
    }
}
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.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.