manager: declarative configuration examples

Configuration examples

A current detailed configuration datamodel can be seen here.

Minimal config

The minimal configuration to start the manager.

id: dev # identifier of the manager instance

Complete config without policy rules

id: dev
hostname: &name manager-dev
nsid: *name
rundir: etc/knot-resolver/runtime
workers: 1
management:
  interface: 127.0.0.1@5000 # or unix-socket: '/path/to/unix-socket'
webmgmt:
  interface: 127.0.0.1@5000
  tls: true
  cert-file: /path/to/file.cert
  key-file: /path/to/file.key
supervisor:
  backend: systemd-session
  watchdog:
    qname: nic.cz.
    qtype: AAAA
options:
  glue-checking: normal # strict, permissive
  qname-minimisation: true
  query-loopback: false
  reorder-rrset: true
  query-case-randomization: false
  priming: true
  rebinding-protection: false
  refuse-no-rd: true
  time-jump-detection: true
  violators-workarounds: false
  serve-stale: false
  prediction: # can be also set to 'false' or 'true'
    window: 15m
    period: 24
network:
  listen:
    - interface: 127.0.0.1@5353 # or unix-socket: /path/to/socket
      kind: dns # xdp, dot, doh-legacy, doh2
      freebind: false
  do-ipv4: true
  do-ipv6: true
  tcp-pipeline: 100
  edns-tcp-keepalive: true
  edns-buffer-size:
    upstream: 1232B
    downstream: 1232B
  address-renumbering:
    - source: 10.10.10.0/24
      destination: 192.168.1.0
  tls:
    cert-file: /path/to/file.cert
    key-file: /path/to/file.key
    sticket-secret: some-secret # or sticket-secret-file: /path/to/secret
    auto-discovery: false
    padding: true # or int value 0-512
  proxy-protocol:
    allow: [172.22.0.1, 172.18.1.0/24]
static-hints:
  ttl: 1d
  nodata: true
  etc-hosts: true
  root-hints:
    j.root-servers.net.: [2001:503:c27::2:30, 192.58.128.30]
  root-hints-file: /path/to/root.hints
  hints:
    foo.bar: [127.0.0.1]
  hints-files: [/path/to/custom.hints]
# policy rules examples will be separate
# views, slices, policy, rpz, stub-zones, forward-zones
cache:
  garbage-collector: true
  storage: /var/cache/knot-resolver
  size-max: 100M
  ttl-min: 5s
  ttl-max: 6d
  ns-timeout: 1000ms
  prefill:
    - origin: '.'
      url: https://www.internic.net/domain/root.zone
      refresh-interval: 1d
      ca-file: /etc/pki/tls/certs/ca-bundle.crt
dnssec: # can be set to 'false' or 'true'
  trust-anchor-sentinel: true
  trust-anchor-signal-query: true
  time-skew-detection: true
  keep-removed: 0
  refresh-time: 10s
  hold-down-time: 30d
  trust-anchors:
    - . 3600 IN DS 19036 8 2 49AAC11...
  negative-trust-anchors: [bad.boy, example.com]
  trust-anchors-files:
    - file: root.key
      read-only: false
dns64: # can be set to 'false' or 'true'
  prefix: 64:ff9b::/96
logging:
  level: notice   # crit, err, warning, notice, info, debug
  target: syslog  # stderr, stdout
  groups: [manager, cache]
  dnssec-bogus: false
  dnstap: # can be set to 'false'
    unix-socket: /tmp/dnstap.sock
    log-queries: true
    log-responses: true
    log-tcp-rtt: true
  debugging:
    assertion-abort: false
    assertion-fork: 5m
monitoring:
  enabled: lazy # manager-only, always
  graphite:
    prefix: *name
    host: 127.0.0.1 # or domain-name
    port: 2003
    interval: 5s
    tcp: false
lua:
  script-only: false  # if 'true', no declarative config is used, just lua script
  script: | # or script-file: '/path/to/lua/script.lua'
    -- this is lua script

Policy rules and config

These are only examples, there is no guarantee that they will work together in single configuration.

# Definition of views
# https://knot-resolver.readthedocs.io/en/stable/modules-view.html?highlight=views#views-and-acls
views:
  view-1:
    subnets: [127.0.0.1, '::']
    options: [no-minimize]
  view-2:
    tsig: [\5mykey]


slices:
  # Forwarding to multiple targets
  # https://knot-resolver.readthedocs.io/en/stable/modules-policy.html?highlight=slices#forwarding-to-multiple-targets
  - function: randomize-psl
    actions:
      - action: forward
        servers:
          - address: 192.0.2.1
            hostname: res.example.com
      - action: forward
        servers:
          - address: 193.17.47.1
            hostname: odvr.nic.cz
          - address: 185.43.135.1
            hostname: odvr.nic.cz


# RPZ blocklist
# https://knot-resolver.readthedocs.io/en/stable/modules-policy.html?highlight=rpz#policy.rpz
rpz:
  - action: deny
    file: /etc/knot-resolver/blocklist.rpz
    watch: true
    message: domain blocked by your resolver operator


# Policy rules examples
# https://knot-resolver.readthedocs.io/en/stable/modules-policy.html
policy:
  # Mirror query trafic
  - action: mirror
    servers: [127.0.0.2]
  # Whitelist 'good.example.com'
  - action: pass
    filter:
      pattern: good.example.com.
  # Deny query based on suffix filter for 'view-1' and 'view-2'
  - action: deny
    filter:
      suffix: example.net
    views: [view-1, view-2]
  # Change IPv4 address and TTL for example.com
  - action: answer
    filter:
      domain: example.com
    answer:
      rtype: A
      rdata: 192.0.2.7
      ttl: 300s


# Stub zones
# https://knot-resolver.readthedocs.io/en/stable/modules-policy.html?highlight=stub#policy.STUB
stub-zones:
  - name: 1.168.192.in-addr.arpa
    servers: [192.0.2.1@5353]
  # internal-only domain
  # https://knot-resolver.readthedocs.io/en/stable/quickstart-config.html?highlight=local%20domains#internal-only-domains
  - name: company.example
    servers: [192.0.2.44]
    options: [no-cache]


# Forwarding
# https://knot-resolver.readthedocs.io/en/stable/modules-policy.html?highlight=stub#forwarding
forward-zones:
  # Forward all queries to public resolvers https://www.nic.cz/odvr
  - name: '.'
    servers: [2001:148f:fffe::1, 2001:148f:ffff::1, 185.43.135.1, 193.14.47.1]
  # TLS forward, server authenticated using hostname and system-wide CA certificates
  # https://knot-resolver.readthedocs.io/en/stable/modules-policy.html?highlight=forward#tls-examples
  - name: '.'
    tls: true
    servers:
      - address: 192.0.2.1
        pin-sha256: Wg==
      - address: 2001:DB8::d0c
        hostname: res.example.com
        ca-file: /etc/knot-resolver/tlsca.crt