Configuration Overview

By default, Knot Resolver configuration is located in the /etc/knot-resolver/config.yaml file. The configuration file uses declarative format YAML version 1.1, but you can also write the same as JSON. To quickly learn about the format, you can have a look at Learn YAML in Y minutes.

Note

You can see some configuration examples in Getting Started chapter.

Validation

The configuration has to pass a validation step before being used in the resolver. The validation checks for conformance in predefined configuration datamodel. You can use kresctl validate to check your configuration before using it in the resolver.

Warning

Some validation steps are however dynamic (for example resolving of interface names) and can not be premodeled for validation and even completed without running the resolver.

Tip

Whenever a configuration is loaded and the validation fails, we attempt to log a detailed error message explaining what the problem was. For example, it could look like the following.

ERROR:knot_resolver_manager.server:multiple configuration errors detected:
        [/management/interface] invalid port number 66000
        [/logging/level] 'noticed' does not match any of the expected values ('crit', 'err', 'warning', 'notice', 'info', 'debug')

If you happen to find a rejected configuration with unhelpful or confusing error message, please report it as a bug.

JSON Schema

While originally the configuration is modeled in Python source code, it can be represented as a JSON schema. JSON schema is NOT used to validate the configuration, it is the other way to help understand the configuration structure. An easy way to see the complete configuration.

Getting the JSON Schema

  • The JSON schema can be downloaded here (valid only for the version of the resolver this documentation was generated for).

  • The kresctl schema command outputs the JSON schema of the currently installed version as well. It does not require a running resolver.

  • The JSON schema can also be obtained from a running resolver by sending a HTTP GET request to the path /schema on the management API (by default a Unix socket at /var/run/knot-resolver/manager.sock).

Tip

For the schema readability, some graphical visualizer can be used, for example this one.

Interactive visualization

The following visualization is interactive and offers good overview of the configuration structure.

Open in a new tab.