kresctl utility¶

Command-line utility that helps communicate with the management API. It also provides tooling to work with declarative configuration (validate, convert).

-h, --help¶: Shows help message. It can be also used with every command for its help message.

Connecting to the management API¶

Most commands require connection to the management API. With a standard Knot Resolver installation using distribution packages, kresctl should communicate with the running resolver without any additional configuration. For nonstandard 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 /var/run/knot-resolver/manager.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>¶: Optional, path to Unix-domain socket or network interface of the management API. Cannot be used together with --socket.

$ 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>¶: Optional, path to Knot Resolver declarative configuration to retrieve Unix-domain socket or network interface of the management API from. Cannot be used together with --socket.

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

Commands¶

The following possitional arguments determine what kind of command will be executed. Only one of these arguments can be selected during the execution of a single krestctl command.

config¶

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

Operations:

Use one of the following operations to be performed on the configuration.

get¶

Get current configuration from the resolver.

-p <path>, --path <path>¶: Optional, path (JSON pointer, RFC6901) to the configuration resources. By default, the entire configuration is selected.

--json, --yaml¶

Default: --json

Get configuration data in JSON or YAML format.

<file>¶: Optional, path to the file where to save exported configuration data. If not specified, data will be printed.

set¶

Set new configuration for the resolver.

-p <path>, --path <path>¶: Optional, path (JSON pointer, RFC6901) to the configuration resources. By default, the entire configuration is selected.

--json, --yaml¶

Default: --json

Set configuration data in JSON or YAML format.

[ <file> | <value> ]: Optional, path to file with new configuraion or new configuration value. If not specified, value will be readed from stdin.

delete¶

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

-p <path>, --path <path>¶: Optional, path (JSON pointer, RFC6901) to the configuration resources. By default, the entire configuration is selected.

This command reads current network configuration subtree from the resolver and exports it to file in YAML format.

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

Next command changes workers configuration to 8.

$ kresctl config set -p /workers 8

metrics¶

Reads agregated metrics data in Propmetheus format directly from the running resolver. Requires connection to the management API.

<file>¶: Optional, file where to export Prometheus metrics. If not specified, the metrics are printed.

$ kresctl metrics ./metrics/data.txt

schema¶

Shows JSON-schema repersentation of the Knot Resolver’s configuration.

-l, --live¶: Get configuration JSON-schema from the running resolver. Requires connection to the management API.

<file>¶: Optional, file where to export JSON-schema. If not specified, the JSON-schema is printed.

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

validate¶

Validates configuration in JSON or YAML format.

--no-strict¶: Ignore strict rules during validation, e.g. path/file existence.

<input_file>¶: File with configuration in YAML or JSON format.

$ kresctl validate input-config.json

convert¶

Converts JSON or YAML configuration to Lua script.

--no-strict¶: Ignore strict rules during validation, e.g. path/file existence.

<input_file>¶: File with configuration in YAML or JSON format.

<output_file>¶: Optional, output file for converted configuration in Lua script. If not specified, converted configuration is printed.

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

reload¶: Tells the resolver to reload YAML configuration file. Old processes are replaced by new ones (with updated configuration) using rolling restarts. So there will be no DNS service unavailability during reload operation. Requires connection to the management API.

stop¶: Tells the resolver to shutdown everthing. No process will run after this command. Requires connection to the management API.