# Configuration Overview

Configuration file is named `/etc/knot-resolver/kresd.conf` and is read when you execute Knot Resolver using systemd commands described in section Startup. [1]

## Syntax

The configuration file syntax allows you to specify different kinds of data:

> - `group.option = 123456`

> - `group.option = "string value"`

> - `group.command(123456, "string value")`

> - `group.command({ key1 = "value1", key2 = 222, key3 = "third value" })`

> - `globalcommand(a_parameter_1, a_parameter_2, a_parameter_3, etc)`

> - `-- any text after -- sign is ignored till end of line`

Following configuration file snippet starts listening for unencrypted and also encrypted DNS queries on IP address 192.0.2.1, and sets cache size.

    -- this is a comment: listen for unencrypted queries
    net.listen('192.0.2.1')
    -- another comment: listen for queries encrypted using TLS on port 853
    net.listen('192.0.2.1', 853, { kind = 'tls' })
    -- 10 MB cache is suitable for a very small deployment
    cache.size = 10 * MB

Tip

When copy&pasting examples from this manual please pay close attention to brackets and also line ordering - order of lines matters.

The configuration language is in fact Lua script, so you can use full power of this programming language. See article Learn Lua in 15 minutes for a syntax overview.

When you modify configuration file on disk restart resolver process to get changes into effect. See chapter Zero-downtime restarts if even short outages are not acceptable for your deployment.

[1]

If you decide to run binary `/usr/sbin/kresd` manually (instead of using systemd) do not forget to specify `-c` option with path to configuration file, otherwise `kresd` will read file named `config` from its current working directory.

## Documentation Conventions

Besides text configuration file, Knot Resolver also supports interactive and dynamic configuration using scripts or external systems, which is described in chapter Run-time reconfiguration. Through this manual we present examples for both usage types - static configuration in a text file (see above) and also the interactive mode.

The interactive prompt is denoted by `>`, so all examples starting with `>` character are transcripts of user (or script) interaction with Knot Resolver and resolver’s responses. For example:

    > -- this is a comment entered into interactive prompt
    > -- comments have no effect here
    > -- the next line shows a command entered interactively and its output
    > log_level()
    'notice'
    > -- the previous line without > character is output from log_level() command

Following example demonstrates how to interactively list all currently loaded modules, and includes multi-line output:

    > modules.list()
    {
        'iterate',
        'validate',
        'cache',
        'ta_update',
        'ta_signal_query',
        'policy',
        'priming',
        'detect_time_skew',
        'detect_time_jump',
        'ta_sentinel',
        'edns_keepalive',
        'refuse_nord',
        'watchdog',
    }

Before we dive into configuring features, let us explain modularization basics.

## Modules

Knot Resolver functionality consists of separate modules, which allow you to mix-and-match features you need without slowing down operation by features you do not use.

This practically means that you need to load module before using features contained in it, for example:

    -- load module and make dnstap features available
    modules.load('dnstap')
    -- configure dnstap features
    dnstap.config({
            socket_path = "/tmp/dnstap.sock"
    })

Obviously ordering matters, so you have to load module first and configure it after it is loaded.

Here is full reference manual for module configuration:

modules.list()
  Returns:

    List of loaded modules.

modules.load(name)
  Parameters:

    name (string) – Module name, e.g. “hints”

  Returns:

    `true` if modules was (or already is) loaded, error otherwise.

  Load a module by name.

modules.unload(name)
  Parameters:

    name (string) – Module name, e.g. “detect_time_jump”

  Returns:

    `true` if modules was unloaded, error otherwise.

  Unload a module by name. This is useful for unloading modules loaded by default, mainly for debugging purposes.

Now you know what configuration file to modify, how to read examples and what modules are so you are ready for a real configuration work!