/doc/kresd.8
/doc/texinfo
/doc/_static/config.schema.json
-/doc/config-schema.md
+/doc/_static/schema_doc*
+/doc/config-schema-body.md
/ephemeral_key.pem
/install-sh
/libkres.pc
'sphinx.ext.viewcode',
'sphinx_tabs.tabs',
'breathe',
- 'myst_parser',
+ 'sphinx_mdinclude',
]
# Breathe configuration
--- /dev/null
+
+
+
+.. _config-syntax:
+
+Syntax
+======
+
+The configuration file syntax allows you to specify different kinds of data:
+
+ - ``group.option = 123456``
+ - ``group.option = "string value"``
+ - ``group.command(123456, "string value")``
+ - ``group.command({ key1 = "value1", key2 = 222, key3 = "third value" })``
+ - ``globalcommand(a_parameter_1, a_parameter_2, a_parameter_3, etc)``
+ - ``-- any text after -- sign is ignored till end of line``
+
+Following **configuration file snippet** starts listening for unencrypted and also encrypted DNS queries on IP address 192.0.2.1, and sets cache size.
+
+.. code-block:: lua
+
+ -- this is a comment: listen for unencrypted queries
+ net.listen('192.0.2.1')
+ -- another comment: listen for queries encrypted using TLS on port 853
+ net.listen('192.0.2.1', 853, { kind = 'tls' })
+ -- 10 MB cache is suitable for a very small deployment
+ cache.size = 10 * MB
+
+.. tip::
+ When copy&pasting examples from this manual please pay close
+ attention to brackets and also line ordering - order of lines matters.
+
+ The configuration language is in fact Lua script, so you can use full power
+ of this programming language. See article
+ `Learn Lua in 15 minutes`_ for a syntax overview.
+
+When you modify configuration file on disk restart resolver process to get
+changes into effect. See chapter :ref:`systemd-zero-downtime-restarts` if even short
+outages are not acceptable for your deployment.
+
+.. [#] If you decide to run binary ``/usr/sbin/kresd`` manually (instead of
+ using systemd) do not forget to specify ``-c`` option with path to
+ configuration file, otherwise ``kresd`` will read file named ``config`` from
+ its current working directory.
+
+Documentation Conventions
+=========================
+
+Besides text configuration file, Knot Resolver also supports interactive and dynamic configuration using scripts or external systems, which is described in chapter :ref:`runtime-cfg`. Through this manual we present examples for both usage types - static configuration in a text file (see above) and also the interactive mode.
+
+The **interactive prompt** is denoted by ``>``, so all examples starting with ``>`` character are transcripts of user (or script) interaction with Knot Resolver and resolver's responses. For example:
+
+.. code-block:: lua
+
+ > -- this is a comment entered into interactive prompt
+ > -- comments have no effect here
+ > -- the next line shows a command entered interactively and its output
+ > log_level()
+ 'notice'
+ > -- the previous line without > character is output from log_level() command
+
+Following example demonstrates how to interactively list all currently loaded modules, and includes multi-line output:
+
+.. code-block:: lua
+
+ > modules.list()
+ {
+ 'iterate',
+ 'validate',
+ 'cache',
+ 'ta_update',
+ 'ta_signal_query',
+ 'policy',
+ 'priming',
+ 'detect_time_skew',
+ 'detect_time_jump',
+ 'ta_sentinel',
+ 'edns_keepalive',
+ 'refuse_nord',
+ 'watchdog',
+ }
+
+
+Before we dive into configuring features, let us explain modularization basics.
+
+.. include:: ../daemon/bindings/modules.rst
+
+Now you know what configuration file to modify, how to read examples and what modules are so you are ready for a real configuration work!
+
+.. _`Learn Lua in 15 minutes`: http://tylerneylon.com/a/learn-lua/
\ No newline at end of file
Configuration Overview
**********************
-Configuration file is named ``/etc/knot-resolver/kresd.conf`` and is read when
-you execute Knot Resolver using systemd commands described in section
-:ref:`gettingstarted-startup`. [#]_
+Configuration file is by default named ``/etc/knot-resolver/config.yml``.
+Different configuration file can be loaded by using command line option
+``-c / --config``.
-.. _config-syntax:
Syntax
======
-The configuration file syntax allows you to specify different kinds of data:
+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/>_`.
- - ``group.option = 123456``
- - ``group.option = "string value"``
- - ``group.command(123456, "string value")``
- - ``group.command({ key1 = "value1", key2 = 222, key3 = "third value" })``
- - ``globalcommand(a_parameter_1, a_parameter_2, a_parameter_3, etc)``
- - ``-- any text after -- sign is ignored till end of line``
-Following **configuration file snippet** starts listening for unencrypted and also encrypted DNS queries on IP address 192.0.2.1, and sets cache size.
+Schema
+======
-.. code-block:: lua
+The configuration has to pass a validation step before being used. The validation mainly
+checks for conformance to our :ref:`configuration-schema`.
- -- this is a comment: listen for unencrypted queries
- net.listen('192.0.2.1')
- -- another comment: listen for queries encrypted using TLS on port 853
- net.listen('192.0.2.1', 853, { kind = 'tls' })
- -- 10 MB cache is suitable for a very small deployment
- cache.size = 10 * MB
.. tip::
- When copy&pasting examples from this manual please pay close
- attention to brackets and also line ordering - order of lines matters.
-
- The configuration language is in fact Lua script, so you can use full power
- of this programming language. See article
- `Learn Lua in 15 minutes`_ for a syntax overview.
-
-When you modify configuration file on disk restart resolver process to get
-changes into effect. See chapter :ref:`systemd-zero-downtime-restarts` if even short
-outages are not acceptable for your deployment.
-
-.. [#] If you decide to run binary ``/usr/sbin/kresd`` manually (instead of
- using systemd) do not forget to specify ``-c`` option with path to
- configuration file, otherwise ``kresd`` will read file named ``config`` from
- its current working directory.
-
-Documentation Conventions
-=========================
-
-Besides text configuration file, Knot Resolver also supports interactive and dynamic configuration using scripts or external systems, which is described in chapter :ref:`runtime-cfg`. Through this manual we present examples for both usage types - static configuration in a text file (see above) and also the interactive mode.
-
-The **interactive prompt** is denoted by ``>``, so all examples starting with ``>`` character are transcripts of user (or script) interaction with Knot Resolver and resolver's responses. For example:
-
-.. code-block:: lua
-
- > -- this is a comment entered into interactive prompt
- > -- comments have no effect here
- > -- the next line shows a command entered interactively and its output
- > log_level()
- 'notice'
- > -- the previous line without > character is output from log_level() command
-
-Following example demonstrates how to interactively list all currently loaded modules, and includes multi-line output:
-
-.. code-block:: lua
-
- > modules.list()
- {
- 'iterate',
- 'validate',
- 'cache',
- 'ta_update',
- 'ta_signal_query',
- 'policy',
- 'priming',
- 'detect_time_skew',
- 'detect_time_jump',
- 'ta_sentinel',
- 'edns_keepalive',
- 'refuse_nord',
- 'watchdog',
- }
-
-
-Before we dive into configuring features, let us explain modularization basics.
-
-.. include:: ../daemon/bindings/modules.rst
-
-Now you know what configuration file to modify, how to read examples and what modules are so you are ready for a real configuration work!
-
-.. _`Learn Lua in 15 minutes`: http://tylerneylon.com/a/learn-lua/
+ 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:
+
+ .. 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')
+
+ If you happen to find a rejected configuration with unhelpful or confusing error message, please report it as a bug.
+++ /dev/null
-# Config schema reference
-
-The following section is automatically generated from the [configuration JSON schema](_static/config.schema.json) and can be used as a quick reference.
-
--- /dev/null
+Configuration schema
+====================
+
+
+The configuration schema describes the structure of accepted configuration files (or objects via the API). While originally specified in Python source code, it can be visualized as a `JSON schema <https://json-schema.org/>_`.
+
+Getting the JSON schema
+-----------------------
+
+1. The JSON schema can be obtained from a running Resolver by sending a HTTP GET request to the path ``/schema`` on the management socket (by default a Unix socket at ``/var/run/knot-resolver/manager.sock``).
+2. The ``kresctl schema`` command outputs the schema of the currently installed version as well. It does not require a running resolver.
+3. JSON schema for the most recent Knot Resolver version can be `downloaded here <_static/config.schema.json>_`.
+
+Validating you configuration
+----------------------------
+
+As mentioned above, the JSON schema is NOT used to validate the configuration in the Knot Resolver. It's the other way around, the validation process can generate JSON schema that can help you understand the configuration structure. Some validation steps are however dynamic (for example resolving of interface names) and can not be expressed using JSON schema and cannot be even completed without running full Resolver.
+
+.. note::
+ When using the API to change configuration in runtime, your change can be rejected by the validation step even though Knot Resolver would start just fine with the given changed configuration. Some validation steps within the Resolver are dynamic and they are dependent on both your previous configuration and the new one. For example, if you try to change the management socket, the validation will fail even though the new provided address is perfectly valid. Chaning the management socket while running is not supported.
+
+Most of the validation is however static and you can use the ``kresctl validate`` command to check your configuration file for most errors before actually running the Resolver.
+
+
+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>
+
+
+Text-based configuration schema description
+-------------------------------------------
+
+Following, you can find the JSON schema flattened textual representation. It's not meant to be read top-to-bottom, however it can be used as a quick lookup reference.
+
+.. mdinclude:: config-schema-body.md
+
error('missing doc dependency: python jsonschema2md')
endif
- myst_parser = run_command(python, '-c', 'import myst_parser', check: false)
- if myst_parser.returncode() != 0
- error('missing doc dependency: python myst_parser')
+ jsonschemaforhumans = run_command(python, '-c', 'import json_schema_for_humans', check: false)
+ if jsonschemaforhumans.returncode() != 0
+ error('missing doc dependency: python json-schema-for-humans')
endif
message('------------------------')
sphinx-tabs
breathe
jsonschema2md
-myst_parser
\ No newline at end of file
+json-schema-for-humans
+sphinx_mdinclude
\ No newline at end of file
# SPDX-License-Identifier: GPL-3.0-or-later
cd "$(dirname ${0})/.."
-
# generate JSON schema for the manager's declarative config
pushd manager
## the following python command should hopefully run without any dependencies except for standard python
mkdir -p ../doc/_static/
python3 -m knot_resolver_manager.cli schema > ../doc/_static/config.schema.json
+generate-schema-doc --config expand_buttons=true ../doc/_static/config.schema.json ../doc/_static/schema_doc.html
-# generate readable version of the JSON schema. The command bellow generates a markdown document, prepends a header and lowers priority of all headings by one.
-cat ../doc/config-schema-header.md <(jsonschema2md ../doc/_static/config.schema.json /dev/stdout | sed 's/^#/##/') > ../doc/config-schema.md
+# generate readable version of the JSON schema
+# we could replace jsonschema2md with the following at some point in the future:
+#generate-schema-doc --config template_name=md --config show_toc=false ../doc/_static/config.schema.json ../doc/_static/schema_doc.md
+jsonschema2md ../doc/_static/config.schema.json /dev/stdout | sed 's/^#/###/' > ../doc/config-schema-body.md
popd
projects / thirdparty / knot-resolver.git / commitdiff
