kresctl utility

A command line utility that communicates with the management API. It also provides tooling to work with the declarative configuration (validate, convert).

-h, --help: Shows the help message. It can be also used with each command to show its help message.

Connecting to the management API

Most commands require connection to the management API. With a standard Knot Resolver installation from distribution packages, kresctl should communicate with the running resolver without any additional configuration. For non-standard installations and deployments, you may need to use either the --config or --socket option to tell kresctl where to look for the API.

If the management key is not present in the configuration file, kresctl attempts to connect to the /run/knot-resolver/kres-api.sock Unix-domain socket, which is the Manager’s default communication channel.

By default, kresctl tries to find the correct communication channel in /etc/knot-resolver/config.yaml or, if present, the file specified by the KRES_MANAGER_CONFIG environment variable.

-s <socket>, --socket <socket>

Path to the management API Unix-domain socket or network interface.

Cannot be used together with --config.

$ kresctl --socket http://localhost:5000 {command} # network interface, port 5000
$ kresctl --socket /path/to/socket.sock {command}  # unix-domain socket location

-c <config>, --config <config>

Path to Knot Resolver’s declarative configuration to retrieve the management API’s Unix-domain socket or network interface.

Cannot be used together with --socket.

$ kresctl --config /path/to/config.yaml {command}

Commands

The following positional arguments determine what kind of command will be executed. Only one of these arguments may be selected during the execution of a single kresctl command.

config

Performs operations on the running resolver’s configuration. Requires a connection to the management API.

Operations

The following operations may be performed on the configuration:

get

Get current configuration from the resolver.

-p <path>, --path <path>: Path (JSON pointer, RFC 6901) to the configuration resources. By default, the entire configuration tree is selected.

--json, --yaml

Default:: --json

Get configuration data in JSON or YAML format.

[file]: Optional. The path to the file where the exported configuration data will be saved. If not specified, the data will be printed into stdout.

set

Set new configuration for the resolver.

-p <path>, --path <path>: Path (JSON pointer, RFC 6901) to the configuration resources. By default, the entire configuration tree is selected.

--json, --yaml

Default:: --json

Set configuration data in JSON or YAML format.

[file|value]: Optional. The path to file with the new configuration, or the new configuration value. If not specified, the value will be read from stdin.

delete

Delete the given configuration property or list item at the given index.

-p <path>, --path <path>: Path (JSON pointer, RFC 6901) to the configuration resources. By default, the entire configuration tree is selected.

The following command reads the current network configuration subtree from the resolver and exports it to a file in YAML format:

$ kresctl config get --yaml -p /network ./network-config.yaml

The following command changes the workers configuration to 8:

$ kresctl config set -p /workers 8

migrate

Migrates JSON or YAML configuration to the newer version.

--json, --yaml

Default:: –yaml

Optional, get migrated configuration data in JSON or YAML format.

input_file: File with configuration in YAML or JSON format.

[output_file]: Optional, output file for migrated configuration in desired output format. If not specified, the migrated configuration is printed into stdout.

metrics

Get aggregated metrics from the running resolver in JSON format (default) or optionally in Prometheus format. The prometheus-client Python package needs to be installed if you wish to use the Prometheus format.

Requires a connection to the management HTTP API.

--prometheus: Get metrics in Prometheus format if dependencies are met in the resolver.

[file]: Optional. The file into which metrics will be exported. If not specified, the metrics are printed into stdout.

$ kresctl metrics ./kres-metrics.json
$ kresctl metrics --prometheus

cache clear

Purge cache records matching the specified criteria.

--exact-name: If set, only records with the exact same name are removed, not the whole subtree.

--rr-type <rr-type>

The record type to remove. Only supported together with --exact-name.

Optional.

--chunk-size <chunk-size>

Default:: 100

The number of records to remove in a single round.

The purpose is to prevent the resolver from blocking for too long. The resolver repeats the command after at least one millisecond, until all the matching data is cleared.

[name]

The subtree to purge.

If not provided, the whole cache is purged (and all other parameters to this command are ignored).

$ kresctl cache clear
$ kresctl cache clear example.com.
$ kresctl cache clear --exact-name example.com.

schema

Shows a JSON-schema representation of Knot Resolver’s configuration.

-l, --live

Get the configuration JSON-schema from the running resolver.

Requires a connection to the management API.

[file]

The target file, where the schema is to be exported.

If not specified, the schema is printed into stdout.

$ kresctl schema --live ./mydir/config-schema.json

validate

Validate declarative configuration.

--strict

Enable strict rules during validation.

During strict validation, the existence and access rights of paths are also checked. However, if you are using an additional file system permission control mechanism, such as access control lists (ACLs), this validation will likely fail. This is because the validation runs under a different user/group than the resolver itself and attempts to access the configured paths directly.

[<input_file> ...]

Default:: /etc/knot-resolver/config.yaml

Optional, file or combination of files with the declarative configuration in YAML or JSON format.

$ kresctl validate config.yaml config.additional.json

convert

Convert declarative configuration to a Lua script.

--strict

Enable strict rules during validation.

During strict validation, the existence and access rights of paths are also checked. However, if you are using an additional file system permission control mechanism, such as access control lists (ACLs), this validation will likely fail. This is because the validation runs under a different user/group than the resolver itself and attempts to access the configured paths directly.

--type=<worker|policy-loader>

Which type of Lua script to generate.

worker generates a script for the daemon (default)
policy-loader generates a script for the one-shot policy loader, which generates a rule database based on views, local-data, and forward configuration

[-o, --output <output_file>]

Optional. The output file for converted Lua configuration.

If not specified, the converted configuration is printed into stdout.

[<input_file> ...]

Default:: /etc/knot-resolver/config.yaml

Optional, file or combination of files with configuration in YAML or JSON format.

$ kresctl convert -o output-script.lua input-config.yaml

reload

Tells the resolver to reload the declarative configuration file.

Old subprocesses are replaced by new ones (with updated configuration) using rolling restarts, ensuring that the DNS service is not disrupted during the reload operation.

Requires a connection to the management API.

--force: Force a reload, even if the configuration hasn’t changed.

stop

Tells the resolver to shut down. All processes will be stopped after this command is run.

Requires a connection to the management API.