docs: config: overview

diff --git a/doc/config-overview.rst b/doc/config-overview.rst
index f90719d14622bae3685c18a8b7eafebe2981749d..5ea96fb71a935f1d10f1fdbb028bf363095de578 100644 (file)
--- 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 <https://yaml.org/spec/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 <https://learnxinyminutes.com/docs/yaml/>`_.
 
+.. note::
 
-Syntax
-======
+    You can see some configuration examples in :ref:`Getting Started <gettingstarted-config>` chapter.
 
-The configuration file uses `YAML format version 1.1 <https://yaml.org/spec/1.1/>`_.
-To quickly learn about the format, you can have a look at `Learn YAML in Y minutes <https://learnxinyminutes.com/docs/yaml/>`_.
 
+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 <manager-client>` 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 <https://json-schema.org/>`_.
+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 <manager-client>` 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 <manager-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 <https://json-schema.org/>`_ 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 <https://json-schema.app/>`_.
+
+
+Interactive visualization
+-------------------------
+
+The following visualization is interactive and offers good overview of the configuration structure.
+
+.. raw:: html
+
+    <a href="_static/schema_doc.html" target="_blank">Open in a new tab.</a>
+    <iframe src="_static/schema_doc.html" width="100%" style="height: 30vh;"></iframe>

diff --git a/doc/index.rst b/doc/index.rst
index 6665dd38a8a9b254ba14c5d814d2e14e426f82cd..c7dc53e9ecb26fb29dd4b90ed7ace17aa2ffd29e 100644 (file)
--- 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 <gett
    :maxdepth: 3
 
    config-overview
-   config-schema
    usecase-network-interfaces
    config-policy-new
    config-lua