Addresses and services¶

Addresses, ports, protocols, and API calls available for clients communicating with the resolver are configured in network/listen.

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

Protocol/service	`kind`
DNS (unencrypted UDP+TCP, RFC 1034)	`dns`
DNS (unencrypted UDP, using XDP Linux API)	`xdp`
DNS-over-TLS (DoT)	`dot`
DNS-over-HTTPS (DoH)	`doh2`
Legacy DNS-over-HTTPS (DoH)	`doh-legacy`

Note

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

network/listen: <list>¶

unix-socket: <path>¶: Path to a unix domain socket to listen on.

interface: <address or interface>¶: IP address or interface name to listen on. May also be a list of addresses and interface names. Optionally, the port number may be specified using @ as a separator, e.g. 127.0.0.1@3535 or eth0@5353.

port: <1-65535>¶

Default: 53 (dns, xdp), 853 (dot), 443 (doh2, doh-legacy)

Port number to listen on.

kind: dns|xdp|dot|doh2|doh-legacy¶

Default: dns

DNS query transport protocol.

freebind: true|false¶

Default: false

Freebind allows binding to a non-local or not yet available address.

network:
  listen:
    - interface: '::1'  # default port is 53
    - interface: lo
      port: 3535
    - interface: eth0
      kind: dot  # default port is 853
    - interface: [127.0.0.1, '::1']
      kind: doh2  # default port is 443
    - interface: eth0
      port: 5353  # custom port number, default is 53 for XDP
      kind: xdp
    - unix-socket: /tmp/kres-socket  # bind to unix domain socked

Warning

On machines with multiple IP addresses, avoid listening on wildcards like 0.0.0.0 or ::. If a client can be reached through multiple addresses, UDP answers from a wildcard address might pick a wrong source address - most well-behaved clients will then refuse such a response.

PROXYv2 protocol¶

Knot Resolver supports proxies that utilize the PROXYv2 protocol to identify clients.

A PROXY header contains the IP address of the original client who sent a query. This allows the resolver to treat queries as if they actually came from the client’s IP address, rather than the address of the proxy they came through. For example, Views and ACLs are able to work as intended when PROXYv2 is in use.

Allowing usage of the PROXYv2 protocol for all clients would be a security vulnerability, because clients would then be able to spoof their IP addresses via the PROXYv2 header. Because of this, the resolver requires explicit specification of which clients are allowed to send PROXYv2 headers. Queries with PROXYv2 headers from clients who are not explicitly allowed to use the protocol will be discarded.

network/proxy-protocol: false|<options>¶

Default: false

allow: <list of addresses and subnets>¶

Allow usage of the PROXYv2 protocol headers by clients on the specified addresses. It is possible to permit whole networks to send PROXYv2 headers by specifying the network mask using the CIDR notation (e.g. 172.22.0.0/16). IPv4 as well as IPv6 addresses are supported.

If you wish to allow all clients to use PROXYv2 (e.g. because you have this kind of security handled on another layer of your network infrastructure), you can specify a netmask of /0. Please note that this setting is address-family-specific, so this needs to be applied to both IPv4 and IPv6 separately.

network:
  proxy-protocol:
    allow:
      - 172.22.0.1     # allows '172.22.0.1' specifically
      - 172.18.1.0/24  # allows everyone at '172.18.1.*'
      - fe80::/10      # allows everyone at IPv6 link-local
      - '::/0'         # allows all IPv6 (but no IPv4)
      - 0.0.0.0/0      # allows all IPv4 (but no IPv6)

TCP pipeline limit¶

TCP pipeline limit per-client, i.e. the number of outstanding queries that a single client connection can make in parallel.

network/tcp-pipeline: <int>¶

Default: 100

network:
  tcp-pipeline: 50

Warning

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