Type: object

Knot Resolver declarative configuration.

Type: integer Default: 1

Version of the configuration schema. By default it is the latest supported by the resolver, but couple of versions back are be supported as well.

Type: string or null Default: null

Name Server Identifier (RFC 5001) which allows DNS clients to request resolver to send back its NSID along with the reply to a DNS request.

Type: string or null Default: null

Internal DNS resolver hostname. Default is machine hostname.

Type: string Default: "/var/run/knot-resolver"

Directory where the resolver can create files and which will be it's cwd.

Default: 1

The number of running kresd (Knot Resolver daemon) workers. If set to 'auto', it is equal to number of CPUs available.

Type: enum (of string)

Must be one of:

  • "auto"
Type: integer

Value must be greater or equal to 1

Type: integer Default: 160

The maximum number of workers allowed. Cannot be changed in runtime.

Value must be greater or equal to 1

Type: object Default: {"unix_socket": "/var/run/knot-resolver/manager.sock", "interface": null}

Configuration of management HTTP API.

Type: string or null Default: null

Path to unix domain socket to listen to.

Type: string or null Default: null

IP address and port number to listen to.

Type: object or null Default: null

Configuration of legacy web management endpoint.

Type: string or null Default: null

Path to unix domain socket to listen to.

Type: string or null Default: null

IP address or interface name with port number to listen to.

Type: boolean Default: false

Enable/disable TLS.

Type: string or null Default: null

Path to certificate file.

Type: string or null Default: null

Path to certificate key.

Type: object Default: {"glue_checking": "normal", "minimize": true, "query_loopback": false, "reorder_rrset": true, "query_case_randomization": true, "priming": true, "rebinding_protection": false, "refuse_no_rd": true, "time_jump_detection": true, "violators_workarounds": false, "serve_stale": false}

Fine-tuning global parameters of DNS resolver operation.

Type: enum (of string) Default: "normal"

Glue records scrictness checking level.

Must be one of:

  • "normal"
  • "strict"
  • "permissive"

Type: boolean Default: true

Send minimum amount of information in recursive queries to enhance privacy.

Type: boolean Default: false

Permits queries to loopback addresses.

Type: boolean Default: true

Controls whether resource records within a RRSet are reordered each time it is served from the cache.

Type: boolean Default: true

Randomize Query Character Case.

Type: boolean Default: true

Initializing DNS resolver cache with Priming Queries (RFC 8109)

Type: boolean Default: false

Protection against DNS Rebinding attack.

Type: boolean Default: true

Queries without RD (recursion desired) bit set in query are answered with REFUSED.

Type: boolean Default: true

Detection of difference between local system time and expiration time bounds in DNSSEC signatures for '. NS' records.

Type: boolean Default: false

Workarounds for known DNS protocol violators.

Type: boolean Default: false

Allows using timed-out records in case DNS resolver is unable to contact upstream servers.

Type: object Default: {"do_ipv4": true, "do_ipv6": true, "out_interface_v4": null, "out_interface_v6": null, "tcp_pipeline": 100, "edns_tcp_keepalive": true, "edns_buffer_size": {"upstream": "1232B", "downstream": "1232B"}, "address_renumbering": null, "tls": {"cert_file": null, "key_file": null, "sticket_secret": null, "sticket_secret_file": null, "auto_discovery": false, "padding": true}, "proxy_protocol": false, "listen": [{"interface": ["127.0.0.1"], "unix_socket": null, "port": 53, "kind": "dns", "freebind": false}, {"interface": ["::1"], "unix_socket": null, "port": 53, "kind": "dns", "freebind": true}]}

Network connections and protocols configuration.

Type: boolean Default: true

Enable/disable using IPv4 for contacting upstream nameservers.

Type: boolean Default: true

Enable/disable using IPv6 for contacting upstream nameservers.

Type: string or null Default: null

IPv4 address used to perform queries. Not set by default, which lets the OS choose any address.

Type: string or null Default: null

IPv6 address used to perform queries. Not set by default, which lets the OS choose any address.

Type: integer Default: 100

TCP pipeline limit. The number of outstanding queries that a single client connection can make in parallel.

Value must be greater or equal to 0 and lesser or equal to 65535

Type: boolean Default: true

Allows clients to discover the connection timeout. (RFC 7828)

Type: object Default: {"upstream": "1232B", "downstream": "1232B"}

Maximum EDNS payload size advertised in DNS packets. Different values can be configured for communication downstream (towards clients) and upstream (towards other DNS servers).

Type: string Default: "1232B"

Maximum EDNS upstream (towards other DNS servers) payload size.

Must match regular expression: ^(\d+)(B|K|M|G)$

Type: string Default: "1232B"

Maximum EDNS downstream (towards clients) payload size for communication.

Must match regular expression: ^(\d+)(B|K|M|G)$

Type: array of object or null Default: null

Renumbers addresses in answers to different address space.

No Additional Items

Each item of this array must be:

Type: object Default: {"cert_file": null, "key_file": null, "sticket_secret": null, "sticket_secret_file": null, "auto_discovery": false, "padding": true}

TLS configuration, also affects DNS over TLS and DNS over HTTPS.

Type: string or null Default: null

Path to certificate file.

Type: string or null Default: null

Path to certificate key file.

Type: string or null Default: null

Secret for TLS session resumption via tickets. (RFC 5077).

Type: string or null Default: null

Path to file with secret for TLS session resumption via tickets. (RFC 5077).

Type: boolean Default: false

Experimental automatic discovery of authoritative servers supporting DNS-over-TLS.

Default: true

EDNS(0) padding of queries and answers sent over an encrypted channel.

Type: boolean
Type: integer

Value must be greater or equal to 0 and lesser or equal to 512

Default: false

PROXYv2 protocol configuration.

Type: enum (of boolean)

Must be one of:

  • false
Type: object

PROXYv2 protocol configuration.

Type: array

Allow usage of the PROXYv2 protocol headers by clients on the specified addresses.

No Additional Items

Each item of this array must be:

Type: array of object Default: [{"interface": ["127.0.0.1"], "unix_socket": null, "port": 53, "kind": "dns", "freebind": false}, {"interface": ["::1"], "unix_socket": null, "port": 53, "kind": "dns", "freebind": true}]

List of interfaces to listen to and its configuration.

No Additional Items

Each item of this array must be:

Type: object

Configuration of listening interface.

Default: null

IP address or interface name with optional port number to listen to.

Default: null

Path to unix domain socket to listen to.

Type: integer or null Default: null

Port number to listen to.

Type: enum (of string) Default: "dns"

Specifies DNS query transport protocol.

Must be one of:

  • "dns"
  • "xdp"
  • "dot"
  • "doh-legacy"
  • "doh2"

Type: boolean Default: false

Used for binding to non-local address.

Type: array of object or null Default: null

List of views and its configuration.

No Additional Items

Each item of this array must be:

Type: object

Configuration parameters that allow you to create personalized policy rules and other.

Type: array of string

Identifies the client based on his subnet. Rule with more precise subnet takes priority.

No Additional Items

Each item of this array must be:

Type: string or null Default: null

Destination subnet, as an additional condition.

Type: array of enum (of string) or null Default: null

Transport protocol, as an additional condition.

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

  • "udp53"
  • "tcp53"
  • "dot"
  • "doh"
  • "doq"

Type: array of string or null Default: null

Tags to link with other policy rules.

No Additional Items

Each item of this array must be:

Type: string
Must match regular expression: ^(?!-)[a-z0-9-]*[a-z0-9]+$

Type: enum (of string) Default: null

Direct approach how to handle request from clients identified by the view.

Must be one of:

  • "allow"
  • "refused"
  • "noanswer"

Type: object Default: {"minimize": true, "dns64": true}

Configuration options for clients identified by the view.

Type: boolean Default: true

Send minimum amount of information in recursive queries to enhance privacy.

Type: boolean Default: true

Enable/disable DNS64.

Type: object Default: {"ttl": null, "nodata": true, "root_fallback_addresses": null, "root_fallback_addresses_files": null, "addresses": null, "addresses_files": null, "records": null, "rules": null, "rpz": null}

Local data for forward records (A/AAAA) and reverse records (PTR).

Type: string or null Default: null

Default TTL value used for added local data/records.

Must match regular expression: ^(\d+)(us|ms|s|m|h|d)$

Type: boolean Default: true

Use NODATA synthesis. NODATA will be synthesised for matching name, but mismatching type(e.g. AAAA query when only A exists).

Type: array of string or null Default: null

Direct replace of root hints from a zonefile.

No Additional Items

Each item of this array must be:

Type: object or null Default: null

Direct addition of hostname and IP addresses pairs.

Type: array of string or null Default: null

Direct addition of hostname and IP addresses pairs from files in '/etc/hosts' like format.

No Additional Items

Each item of this array must be:

Type: string or null Default: null

Direct addition of records in DNS zone file format.

Type: array of object or null Default: null

Local data rules.

No Additional Items

Each item of this array must be:

Type: object

Local data advanced rule configuration.

Default: null

Hostname(s).


Type: array of string
No Additional Items

Each item of this array must be:

Type: string
Must match regular expression: (?=^.{,253}\.?$)(^(?!\.)((?!-)\.?[a-zA-Z0-9-]{,62}[a-zA-Z0-9])+\.?$)|^\.$
Type: string
Must match regular expression: (?=^.{,253}\.?$)(^(?!\.)((?!-)\.?[a-zA-Z0-9-]{,62}[a-zA-Z0-9])+\.?$)|^\.$

Type: enum (of string) Default: null

Type of subtree.

Must be one of:

  • "empty"
  • "nxdomain"
  • "redirect"

Default: null

Path to file(s) with hostname and IP address(es) pairs in '/etc/hosts' like format.


Type: array of string
No Additional Items

Each item of this array must be:

Type: string or null Default: null

Direct addition of records in DNS zone file format.

Type: array of string or null Default: null

Tags to link with other policy rules.

No Additional Items

Each item of this array must be:

Type: string
Must match regular expression: ^(?!-)[a-z0-9-]*[a-z0-9]+$

Type: string or null Default: null

Optional, TTL value used for these answers.

Must match regular expression: ^(\d+)(us|ms|s|m|h|d)$

Type: boolean or null Default: null

Optional, use NODATA synthesis. NODATA will be synthesised for matching name, but mismatching type(e.g. AAAA query when only A exists).

Type: array of object or null Default: null

List of Response Policy Zones and its configuration.

No Additional Items

Each item of this array must be:

Type: object

Configuration or Response Policy Zone (RPZ).

Type: string

Path to the RPZ zone file.

Type: array of string or null Default: null

Tags to link with other policy rules.

No Additional Items

Each item of this array must be:

Type: string
Must match regular expression: ^(?!-)[a-z0-9-]*[a-z0-9]+$

Type: array of object or null Default: null

List of Forward Zones and its configuration.

No Additional Items

Each item of this array must be:

Type: object

Configuration of forward subtree.


Subtree(s) to forward.

Type: array of string
No Additional Items

Each item of this array must be:

Type: string
Must match regular expression: (?=^.{,253}\.?$)(^(?!\.)((?!-)\.?[a-zA-Z0-9-]{,62}[a-zA-Z0-9])+\.?$)|^\.$
Type: string
Must match regular expression: (?=^.{,253}\.?$)(^(?!\.)((?!-)\.?[a-zA-Z0-9-]{,62}[a-zA-Z0-9])+\.?$)|^\.$


Forward servers configuration.

Type: array of string
No Additional Items

Each item of this array must be:

Type: array of object
No Additional Items

Each item of this array must be:

Type: object

Forward server configuration.


IP address(es) of a forward server.

Type: enum (of string) Default: null

Transport protocol for a forward server.

Must be one of:

  • "tls"

Default: null

Hash of accepted CA certificate.


Type: array of string
No Additional Items

Each item of this array must be:

Type: string
Must match regular expression: ^[A-Za-z\d+/]{86}==$
Type: string
Must match regular expression: ^[A-Za-z\d+/]{86}==$

Type: string or null Default: null

Hostname of the Forward server.

Must match regular expression: (?=^.{,253}\.?$)(^(?!\.)((?!-)\.?[a-zA-Z0-9-]{,62}[a-zA-Z0-9])+\.?$)|^\.$

Type: string or null Default: null

Path to CA certificate file.

Type: object Default: {"authoritative": false, "dnssec": true}

Subtree(s) forward options.

Type: boolean Default: false

The forwarding target is an authoritative server.

Type: boolean Default: true

Enable/disable DNSSEC.

Type: object Default: {"storage": "/var/cache/knot-resolver", "size_max": "100M", "garbage_collector": {"interval": "1s", "threshold": 80, "release": 10, "temp_keys_space": "0M", "rw_deletes": 100, "rw_reads": 200, "rw_duration": "0us", "rw_delay": "0us", "dry_run": false}, "ttl_min": "5s", "ttl_max": "1d", "ns_timeout": "1000ms", "prefill": null, "prefetch": {"expiring": false, "prediction": null}}

DNS resolver cache configuration.

Type: string Default: "/var/cache/knot-resolver"

Cache storage of the DNS resolver.

Type: string Default: "100M"

Maximum size of the cache.

Must match regular expression: ^(\d+)(B|K|M|G)$

Default: {"interval": "1s", "threshold": 80, "release": 10, "temp_keys_space": "0M", "rw_deletes": 100, "rw_reads": 200, "rw_duration": "0us", "rw_delay": "0us", "dry_run": false}

Use the garbage collector (kres-cache-gc) to periodically clear cache.

Type: object

Configuration options of the cache garbage collector (kres-cache-gc).

Type: string Default: "1s"

Time interval how often the garbage collector will be run.

Must match regular expression: ^(\d+)(us|ms|s|m|h|d)$

Type: integer Default: 80

Cache usage in percent that triggers the garbage collector.

Value must be greater or equal to 0 and lesser or equal to 100

Type: integer Default: 10

Percent of used cache to be freed by the garbage collector.

Value must be greater or equal to 0 and lesser or equal to 100

Type: string Default: "0M"

Maximum amount of temporary memory for copied keys (0 = unlimited).

Must match regular expression: ^(\d+)(B|K|M|G)$

Type: integer Default: 100

Maximum number of deleted records per read-write transaction (0 = unlimited).

Value must be greater or equal to 0

Type: integer Default: 200

Maximum number of readed records per read-write transaction (0 = unlimited).

Value must be greater or equal to 0

Type: string Default: "0us"

Maximum duration of read-write transaction (0 = unlimited).

Must match regular expression: ^(\d+)(us|ms|s|m|h|d)$

Type: string Default: "0us"

Wait time between two read-write transactions.

Must match regular expression: ^(\d+)(us|ms|s|m|h|d)$

Type: boolean Default: false

Run the garbage collector in dry-run mode.

Type: enum (of boolean)

Must be one of:

  • false

Type: string Default: "5s"

Minimum time-to-live for the cache entries.

Must match regular expression: ^(\d+)(us|ms|s|m|h|d)$

Type: string Default: "1d"

Maximum time-to-live for the cache entries.

Must match regular expression: ^(\d+)(us|ms|s|m|h|d)$

Type: string Default: "1000ms"

Time interval for which a nameserver address will be ignored after determining that it does not return (useful) answers.

Must match regular expression: ^(\d+)(us|ms|s|m|h|d)$

Type: array of object or null Default: null

Prefill the cache periodically by importing zone data obtained over HTTP.

No Additional Items

Each item of this array must be:

Type: object

Prefill the cache periodically by importing zone data obtained over HTTP.

Type: string

Origin for the imported data. Cache prefilling is only supported for the root zone ('.').

Must match regular expression: (?=^.{,253}\.?$)(^(?!\.)((?!-)\.?[a-zA-Z0-9-]{,62}[a-zA-Z0-9])+\.?$)|^\.$

Type: string

URL of the zone data to be imported.

Type: string Default: "1d"

Time interval between consecutive refreshes of the imported zone data.

Must match regular expression: ^(\d+)(us|ms|s|m|h|d)$

Type: string or null Default: null

Path to the file containing a CA certificate bundle that is used to authenticate the HTTPS connection.

Type: object Default: {"expiring": false, "prediction": null}

These options help keep the cache hot by prefetching expiring records or learning usage patterns and repetitive queries.

Type: boolean Default: false

Prefetch expiring records.

Type: object or null Default: null

Prefetch record by predicting based on usage patterns and repetitive queries.

Type: string Default: "15m"

Sampling window length.

Must match regular expression: ^(\d+)(us|ms|s|m|h|d)$

Type: integer Default: 24

Number of windows that can be kept in memory.

Value must be greater or equal to 1

Default: true

Disable DNSSEC, enable with defaults or set new configuration.

Type: boolean
Type: object

DNSSEC configuration.

Type: boolean Default: true

Allows users of DNSSEC validating resolver to detect which root keys are configured in resolver's chain of trust. (RFC 8509)

Type: boolean Default: true

Signaling Trust Anchor Knowledge in DNSSEC Using Key Tag Query, according to (RFC 8145#section-5).

Type: boolean Default: true

Detection of difference between local system time and expiration time bounds in DNSSEC signatures for '. NS' records.

Type: integer Default: 0

How many removed keys should be held in history (and key file) before being purged.

Value must be greater or equal to 0

Type: string or null Default: null

Force trust-anchors to be updated every defined time periodically instead of relying on (RFC 5011) logic and TTLs. Intended only for testing purposes.

Must match regular expression: ^(\d+)(us|ms|s|m|h|d)$

Type: string Default: "30d"

Modify hold-down timer (RFC 5011). Intended only for testing purposes.

Must match regular expression: ^(\d+)(us|ms|s|m|h|d)$

Type: array of string or null Default: null

List of trust-anchors in DS/DNSKEY records format.

No Additional Items

Each item of this array must be:

Type: array of string or null Default: null

List of domain names representing negative trust-anchors. (RFC 7646)

No Additional Items

Each item of this array must be:

Type: string
Must match regular expression: (?=^.{,253}\.?$)(^(?!\.)((?!-)\.?[a-zA-Z0-9-]{,62}[a-zA-Z0-9])+\.?$)|^\.$

Type: array of object or null Default: null

List of zonefiles where trust-anchors are stored.

No Additional Items

Each item of this array must be:

Type: object

Trust-anchor zonefile configuration.

Type: string

Path to the zonefile that stores trust-anchors.

Type: boolean Default: false

Blocks zonefile updates according to RFC 5011.

Default: false

Disable DNS64 (RFC 6147), enable with defaults or set new configuration.

Type: boolean
Type: object

DNS64 (RFC 6147) configuration.

Type: string Default: "64:ff9b::/96"

IPv6 prefix to be used for synthesizing AAAA records.

Type: string or null Default: null

TTL in CNAME generated in the reverse 'ip6.arpa.' subtree.

Must match regular expression: ^(\d+)(us|ms|s|m|h|d)$

Type: array of string or null Default: null

IPv6 subnets that are disallowed in answer.

No Additional Items

Each item of this array must be:

Type: object Default: {"level": "notice", "target": "stdout", "groups": null, "dnssec_bogus": false, "dnstap": false, "debugging": {"assertion_abort": false, "assertion_fork": "5m"}}

Logging and debugging configuration.

Type: enum (of string) Default: "notice"

Global logging level.

Must be one of:

  • "crit"
  • "err"
  • "warning"
  • "notice"
  • "info"
  • "debug"

Default: "from-env"

Global logging stream target. "from-env" uses $KRESLOGGINGTARGET and defaults to "stdout".

Type: enum (of string)

Must be one of:

  • "syslog"
  • "stderr"
  • "stdout"
Type: enum (of string)

Must be one of:

  • "from-env"

Type: array of enum (of string) or null Default: null

List of groups for which 'debug' logging level is set.

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

  • "manager"
  • "supervisord"
  • "cache-gc"
  • "system"
  • "cache"
  • "io"
  • "net"
  • "ta"
  • "tasent"
  • "tasign"
  • "taupd"
  • "tls"
  • "gnutls"
  • "tls_cl"
  • "xdp"
  • "doh"
  • "dnssec"
  • "hint"
  • "plan"
  • "iterat"
  • "valdtr"
  • "resolv"
  • "select"
  • "zoncut"
  • "cookie"
  • "statis"
  • "rebind"
  • "worker"
  • "policy"
  • "daf"
  • "timejm"
  • "timesk"
  • "graphi"
  • "prefil"
  • "primin"
  • "srvstl"
  • "wtchdg"
  • "nsid"
  • "dnstap"
  • "tests"
  • "dotaut"
  • "http"
  • "contrl"
  • "module"
  • "devel"
  • "renum"
  • "exterr"
  • "rules"
  • "prlayr"

Type: boolean Default: false

Logging a message for each DNSSEC validation failure.

Default: false

Logging DNS requests and responses to a unix socket.

Type: enum (of boolean)

Must be one of:

  • false
Type: object

Logging DNS queries and responses to a unix socket.

Type: string

Path to unix domain socket where dnstap messages will be sent.

Type: boolean Default: true

Log queries from downstream in wire format.

Type: boolean Default: true

Log responses to downstream in wire format.

Type: boolean Default: true

Log TCP RTT (Round-trip time).

Type: object Default: {"assertion_abort": false, "assertion_fork": "5m"}

Advanced debugging parameters for kresd (Knot Resolver daemon).

Type: boolean Default: false

Allow the process to be aborted in case it encounters a failed assertion.

Type: string Default: "5m"

Fork and abord child kresd process to obtain a coredump, while the parent process recovers and keeps running.

Must match regular expression: ^(\d+)(us|ms|s|m|h|d)$

Type: object Default: {"enabled": "lazy", "graphite": false}

Metrics exposisition configuration (Prometheus, Graphite)

Type: enum (of string) Default: "lazy"

configures, whether statistics module will be loaded into resolver

Must be one of:

  • "manager-only"
  • "lazy"
  • "always"

Default: false

optionally configures where should graphite metrics be sent to

Type: enum (of boolean)

Must be one of:

  • false
Type: object


Type: string
Must match regular expression: (?=^.{,253}\.?$)(^(?!\.)((?!-)\.?[a-zA-Z0-9-]{,62}[a-zA-Z0-9])+\.?$)|^\.$

Type: integer Default: 2003

Value must be greater or equal to 1 and lesser or equal to 65535

Type: string Default: ""

Type: string Default: "5s"
Must match regular expression: ^(\d+)(us|ms|s|m|h|d)$

Type: boolean Default: false

Type: object Default: {"script_only": false, "script": null, "script_file": null}

Custom Lua configuration.

Type: boolean Default: false

Ignore declarative configuration and use only Lua script or file defined in this section.

Type: string or null Default: null

Custom Lua configuration script.

Type: string or null Default: null

Path to file that contains Lua configuration script.