From: Aleš Mrázek Date: Tue, 27 Jun 2023 08:20:05 +0000 (+0200) Subject: docs: config: overview X-Git-Tag: v6.0.2~16^2~16 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ca7ebf3aaacde6c68ad5a394a0e92320a9d7b2cf;p=thirdparty%2Fknot-resolver.git docs: config: overview --- diff --git a/doc/config-overview.rst b/doc/config-overview.rst index f90719d14..5ea96fb71 100644 --- a/doc/config-overview.rst +++ b/doc/config-overview.rst @@ -4,30 +4,34 @@ Configuration Overview ********************** -Configuration file is by default named ``/etc/knot-resolver/config.yml``. -Different configuration file can be loaded by using command line option -``-c / --config``. +By default, Knot Resolver configuration is located in the ``/etc/knot-resolver/config.yaml`` file. +The configuration file uses declarative format `YAML version 1.1 `_, +but you can also write the same as JSON. +To quickly learn about the format, you can have a look at `Learn YAML in Y minutes `_. +.. note:: -Syntax -====== + You can see some configuration examples in :ref:`Getting Started ` chapter. -The configuration file uses `YAML format version 1.1 `_. -To quickly learn about the format, you can have a look at `Learn YAML in Y minutes `_. +Validation +========== -Schema -====== +The configuration has to pass a validation step before being used in the resolver. +The validation checks for conformance in predefined configuration datamodel. +You can use :ref:`kresctl validate ` to check your configuration before using it in the resolver. -The configuration has to pass a validation step before being used. The validation mainly -checks for conformance to our :ref:`configuration-schema`. +.. warning:: + Some validation steps are however dynamic (for example resolving of interface names) and can not be premodeled for validation and even completed without running the resolver. .. tip:: + Whenever a configuration is loaded and the validation fails, we attempt to log a detailed - error message explaining what the problem was. For example, it could look like the following: + error message explaining what the problem was. For example, it could look like the following. + + .. code-block:: - .. code_block:: ERROR:knot_resolver_manager.server:multiple configuration errors detected: [/management/interface] invalid port number 66000 [/logging/level] 'noticed' does not match any of the expected values ('crit', 'err', 'warning', 'notice', 'info', 'debug') @@ -35,8 +39,32 @@ checks for conformance to our :ref:`configuration-schema`. If you happen to find a rejected configuration with unhelpful or confusing error message, please report it as a bug. +JSON Schema +=========== + +While originally the configuration is modeled in Python source code, it can be represented as a `JSON schema `_. +JSON schema is NOT used to validate the configuration, it is the other way to help understand the configuration structure. +An easy way to see the complete configuration. + + +Getting the JSON Schema +----------------------- + +* The JSON schema can be `downloaded here <_static/config.schema.json>`_ (valid only for the version of the resolver this documentation was generated for). +* The :ref:`kresctl schema ` command outputs the JSON schema of the currently installed version as well. It does not require a running resolver. +* The JSON schema can also be obtained from a running resolver by sending a HTTP GET request to the path ``/schema`` on the :ref:`management API ` (by default a Unix socket at ``/var/run/knot-resolver/manager.sock``). + .. tip:: - An easy way to see the complete configuration structure is to look at the `JSON schema `_ represention. - The raw JSON schema is available at `this link <_static/config.schema.json>`_ (valid only for the version of resolver this documentation was generated for). For the schema readability, some graphical visualizer can be used, for example `this one `_. + + +Interactive visualization +------------------------- + +The following visualization is interactive and offers good overview of the configuration structure. + +.. raw:: html + + Open in a new tab. + diff --git a/doc/index.rst b/doc/index.rst index 6665dd38a..c7dc53e9e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -25,7 +25,6 @@ If you are a new user, please start with chapter for :ref:`getting started