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 default Knot Resolver configuration, kresctl should communicate with the resolver withou need to specify --socket option. If not, this option must be set for each command.

-s <socket>, --socket <socket>¶

Default: “./manager.sock”

Optional, path to Unix-domain socket or network interface of the management API.

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

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.