From 93590e92b95a7ebb31f50a1a3f5840bd055176a1 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Oto=20=C5=A0=C5=A5=C3=A1va?= Date: Fri, 15 Mar 2024 10:24:36 +0100 Subject: [PATCH] doc/manager-client: adjustments Some language adjustments and improved optionality signalling (optional parameters are usually surrounded by square brackets `[]`, while angle brackets `<>` are usually reserved for mandatory ones). --- doc/user/manager-client.rst | 176 +++++++++++++++++++++--------------- 1 file changed, 101 insertions(+), 75 deletions(-) diff --git a/doc/user/manager-client.rst b/doc/user/manager-client.rst index c7f90346e..70c69aeb8 100644 --- a/doc/user/manager-client.rst +++ b/doc/user/manager-client.rst @@ -8,13 +8,15 @@ kresctl utility .. program:: kresctl -Command-line utility that helps communicate with the :ref:`management 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 `. 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 ` for its help message. + Shows the help message. + It can be also used with each :ref:`command ` to + show its help message. ================================ @@ -23,41 +25,46 @@ Connecting to the management API Most :ref:`commands ` require connection to the :ref:`management API `. With a standard Knot Resolver installation -using :ref:`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 :option:`--config <-c , --config >` or -:option:`--socket <-s , --socket >` option to tell -``kresctl`` where to look for the API. - -If the :ref:`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. +from :ref:`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 +:option:`--config <-c , --config >` or +:option:`--socket <-s , --socket >` option to tell ``kresctl`` +where to look for the API. + +If the :ref:`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 +``/etc/knot-resolver/config.yaml`` or, if present, the file specified by the ``KRES_MANAGER_CONFIG`` environment variable. .. option:: -s , --socket - Optional, path to Unix-domain socket or network interface of the - :ref:`management API `. Cannot be used together with + Path to the :ref:`management API ` Unix-domain socket or + network interface. + + Cannot be used together with :option:`--config <-c , --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 - 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 >`. + 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 >`. -.. code-block:: bash + .. code-block:: bash - $ kresctl --config /path/to/config.yaml {command} + $ kresctl --config /path/to/config.yaml {command} .. _manager-client-commands: @@ -65,19 +72,21 @@ By default, ``kresctl`` tries to find the correct communication channel in 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 @@ -86,8 +95,8 @@ Only one of these arguments can be selected during the execution of a single ``k .. option:: -p , --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 @@ -95,10 +104,11 @@ Only one of these arguments can be selected during the execution of a single ``k Get configuration data in JSON or YAML format. - .. option:: + .. 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 @@ -107,8 +117,8 @@ Only one of these arguments can be selected during the execution of a single ``k .. option:: -p , --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 @@ -116,29 +126,32 @@ Only one of these arguments can be selected during the execution of a single ``k Set configuration data in JSON or YAML format. - .. option:: [ | ] + .. 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 - 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 ` + 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 @@ -146,13 +159,15 @@ Only one of these arguments can be selected during the execution of a single ``k .. 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:: + .. 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 @@ -177,13 +192,17 @@ Only one of these arguments can be selected during the execution of a single ``k :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 @@ -194,18 +213,19 @@ Only one of these arguments can be selected during the execution of a single ``k .. 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:: + .. 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 @@ -214,7 +234,7 @@ Only one of these arguments can be selected during the execution of a single ``k .. option:: validate - Validates configuration in JSON or YAML format. + Validate declarative configuration. .. option:: --no-strict @@ -222,7 +242,7 @@ Only one of these arguments can be selected during the execution of a single ``k .. option:: - File with configuration in YAML or JSON format. + File with the declarative configuration in YAML or JSON format. .. code-block:: bash @@ -231,7 +251,7 @@ Only one of these arguments can be selected during the execution of a single ``k .. option:: convert - Converts JSON or YAML configuration to Lua script. + Convert declarative configuration to a Lua script. .. option:: --no-strict @@ -239,12 +259,14 @@ Only one of these arguments can be selected during the execution of a single ``k .. option:: - File with configuration in YAML or JSON format. + File with the declarative configuration in YAML or JSON format. + + .. option:: [output_file] - .. option:: + 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 @@ -253,14 +275,18 @@ Only one of these arguments can be selected during the execution of a single ``k .. 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. -- 2.47.2