.. program:: kresctl
-Command-line utility that helps communicate with the :ref:`management API <manager-api>`.
-It also provides tooling to work with declarative configuration (:option:`validate`, :option:`convert`).
+A command line utility that communicates with the
+:ref:`management API <manager-api>`. It also provides tooling to work with
+the declarative configuration (:option:`validate`, :option:`convert`).
.. option:: -h, --help
- Shows help message.
- It can be also used with every :ref:`command <manager-client-commands>` for its help message.
+ Shows the help message.
+ It can be also used with each :ref:`command <manager-client-commands>` to
+ show its help message.
================================
Most :ref:`commands <manager-client-commands>` require connection to the
:ref:`management API <manager-api>`. With a standard Knot Resolver installation
-using :ref:`distribution packages <gettingstarted-install>`, ``kresctl``
-should communicate with the running resolver without any additional configuration.
-For nonstandard installations and deployments, you may need to use either
-the :option:`--config <-c <config>, --config <config>>` or
-:option:`--socket <-s <socket>, --socket <socket>>` option to tell
-``kresctl`` where to look for the API.
-
-If the :ref:`management <manager-api>` 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.
+from :ref:`distribution packages <gettingstarted-install>`, ``kresctl`` should
+communicate with the running resolver without any additional configuration. For
+non-standard installations and deployments, you may need to use either the
+:option:`--config <-c <config>, --config <config>>` or
+:option:`--socket <-s <socket>, --socket <socket>>` option to tell ``kresctl``
+where to look for the API.
+
+If the :ref:`management <manager-api>` 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
+``/etc/knot-resolver/config.yaml`` or, if present, the file specified by the
``KRES_MANAGER_CONFIG`` environment variable.
.. option:: -s <socket>, --socket <socket>
- Optional, path to Unix-domain socket or network interface of the
- :ref:`management API <manager-api>`. Cannot be used together with
+ Path to the :ref:`management API <manager-api>` Unix-domain socket or
+ network interface.
+
+ Cannot be used together with
:option:`--config <-c <config>, --config <config>>`.
-.. code-block:: bash
+ .. code-block:: bash
- $ kresctl --socket http://localhost:5000 {command} # network interface, port 5000
- $ kresctl --socket /path/to/socket.sock {command} # unix-domain socket location
+ $ kresctl --socket http://localhost:5000 {command} # network interface, port 5000
+ $ kresctl --socket /path/to/socket.sock {command} # unix-domain socket location
.. option:: -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 :option:`--socket <-s <socket>, --socket <socket>>`.
+ Path to Knot Resolver's declarative configuration to retrieve the management
+ API's Unix-domain socket or network interface.
+
+ Cannot be used together with
+ :option:`--socket <-s <socket>, --socket <socket>>`.
-.. code-block:: bash
+ .. code-block:: bash
- $ kresctl --config /path/to/config.yaml {command}
+ $ kresctl --config /path/to/config.yaml {command}
.. _manager-client-commands:
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.
+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.
.. option:: config
- Performs operations on the running resolver's configuration.
- Requires connection to the management API.
+ Performs operations on the running resolver's configuration. Requires a
+ connection to the management API.
- **Operations:**
+ Operations
+ ----------
- Use one of the following operations to be performed on the configuration.
+ The following operations may be performed on the configuration:
.. option:: get
.. option:: -p <path>, --path <path>
- Optional, path (JSON pointer, RFC6901) to the configuration resources.
- By default, the entire configuration is selected.
+ Path (JSON pointer, :rfc:`6901`) to the configuration resources.
+ By default, the entire configuration tree is selected.
.. option:: --json, --yaml
Get configuration data in JSON or YAML format.
- .. option:: <file>
+ .. option:: [file]
- Optional, path to the file where to save exported configuration data.
- If not specified, data will be printed.
+ Optional. The path to the file where the exported configuration data
+ will be saved. If not specified, the data will be printed into
+ ``stdout``.
.. option:: set
.. option:: -p <path>, --path <path>
- Optional, path (JSON pointer, RFC6901) to the configuration resources.
- By default, the entire configuration is selected.
+ Path (JSON pointer, :rfc:`6901`) to the configuration resources.
+ By default, the entire configuration tree is selected.
.. option:: --json, --yaml
Set configuration data in JSON or YAML format.
- .. option:: [ <file> | <value> ]
+ .. option:: [file|value]
- Optional, path to file with new configuraion or new configuration value.
- If not specified, value will be readed from stdin.
+ Optional. The path to file with the new configuration, or the new
+ configuration value. If not specified, the value will be read from
+ ``stdin``.
.. option:: delete
- Delete given configuration property or list item at the given index.
+ Delete the given configuration property or list item at the given index.
.. option:: -p <path>, --path <path>
- Optional, path (JSON pointer, RFC6901) to the configuration resources.
- By default, the entire configuration is selected.
+ Path (JSON pointer, :rfc:`6901`) to the configuration resources.
+ By default, the entire configuration tree is selected.
- This command reads current ``network`` configuration subtree from the resolver and exports it to file in YAML format.
+ The following command reads the current :ref:`network <config-network>`
+ configuration subtree from the resolver and exports it to a file in YAML
+ format:
.. code-block:: bash
$ kresctl config get --yaml -p /network ./network-config.yaml
- Next command changes workers configuration to ``8``.
+ The following command changes the ``workers`` configuration to ``8``:
.. code-block:: bash
.. option:: metrics
- Reads agregated metrics data in Propmetheus format directly from the running resolver.
- Requires connection to the management API.
+ Reads aggregated metrics data in Prometheus format directly from the running
+ resolver.
+
+ Requires a connection to the management API.
- .. option:: <file>
+ .. option:: [file]
- Optional, file where to export Prometheus metrics.
- If not specified, the metrics are printed.
+ Optional. The file into which Prometheus metrics will be exported.
+ If not specified, the metrics are printed into ``stdout``.
.. code-block:: bash
:default: 100
The number of records to remove in a single round.
- The purpose is not to block the resolver for too long.
- The resolver repeats the command after at least one millisecond, until all the matching data is cleared.
+
+ 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.
.. option:: [name]
The subtree to purge.
- If not provided, the whole cache is purged (and any other parameters are disregarded).
+
+ If not provided, the whole cache is purged (and all other parameters to
+ this command are ignored).
.. code-block:: bash
.. option:: schema
-
- Shows JSON-schema repersentation of the Knot Resolver's configuration.
+ Shows a JSON-schema representation of Knot Resolver's configuration.
.. option:: -l, --live
- Get configuration JSON-schema from the running resolver.
- Requires connection to the management API.
+ Get the configuration JSON-schema from the running resolver.
+
+ Requires a connection to the management API.
- .. option:: <file>
+ .. option:: [file]
- Optional, file where to export JSON-schema.
- If not specified, the JSON-schema is printed.
+ The target file, where the schema is to be exported.
+
+ If not specified, the schema is printed into ``stdout``.
.. code-block:: bash
.. option:: validate
- Validates configuration in JSON or YAML format.
+ Validate declarative configuration.
.. option:: --no-strict
.. option:: <input_file>
- File with configuration in YAML or JSON format.
+ File with the declarative configuration in YAML or JSON format.
.. code-block:: bash
.. option:: convert
- Converts JSON or YAML configuration to Lua script.
+ Convert declarative configuration to a Lua script.
.. option:: --no-strict
.. option:: <input_file>
- File with configuration in YAML or JSON format.
+ File with the declarative configuration in YAML or JSON format.
+
+ .. option:: [output_file]
- .. option:: <output_file>
+ Optional. The output file for converted Lua configuration.
- Optional, output file for converted configuration in Lua script.
- If not specified, converted configuration is printed.
+ If not specified, the converted configuration is printed into
+ ``stdout``.
.. code-block:: bash
.. option:: 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.
+ 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.
.. option:: stop
- Tells the resolver to shutdown everthing.
- No process will run after this command.
- Requires connection to the management API.
+ Tells the resolver to shut down. All processes will be stopped after this
+ command is run.
+
+ Requires a connection to the management API.
projects / thirdparty / knot-resolver.git / commitdiff
