From: Aleš Mrázek Date: Mon, 15 Jan 2024 22:19:47 +0000 (+0100) Subject: doc: separate user and developer documentation X-Git-Tag: v6.0.7~14^2~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d5464a0c29a54c58e87063e11f636679e744cc00;p=thirdparty%2Fknot-resolver.git doc: separate user and developer documentation This separates the documentation into a *blue* user documentation and a *red* developer documentation, resolving problems where similar sections collided in search queries, leading users to the advanced Lua config documentation instead of the preferred declarative config one. It also visually separates the two parts, so that users who do not wish to meddle in Lua immediately see that they're somewhere wrong just by seeing the red colour. --- diff --git a/.gitignore b/.gitignore index c79ea4675..32789e7ca 100644 --- a/.gitignore +++ b/.gitignore @@ -45,8 +45,8 @@ /daemon/lua/trust_anchors.lua /depcomp /distro/tests/*/.vagrant -/doc/.doctrees -/doc/doxyxml +/doc/**/.doctrees +/doc/**/doxyxml /doc/html /doc/kresd.8 /doc/texinfo diff --git a/doc/_static/css/dev.css b/doc/_static/css/dev.css new file mode 100644 index 000000000..c71d8ad27 --- /dev/null +++ b/doc/_static/css/dev.css @@ -0,0 +1,38 @@ +/* SPDX-License-Identifier: GPL-3.0-or-later */ + +.wy-side-nav-search { + background-color: #b92929; /* From logo manual */ +} +.wy-side-nav-search input[type=text] { + border-color: #a42424; +} +.wy-side-nav-search div.version { + color: hsla(0,0%,100%,0.4); +} +.wy-nav-top { + background-color: #b92929; +} + +a { + color: #b92929; +} +a:hover { + color: #d13030; +} +a:visited { + color: #780001; +} +a:visited:hover { + color: #d13030; +} + +.wy-menu-vertical p.caption { + color: #d95555; +} + +.wy-menu-vertical a, .wy-menu-vertical a:hover, .wy-menu-vertical a:visited, +.wy-menu-vertical a:visited:hover { + /* This is here so that the a-rules above do not override the menu colors, + * which should remain grey */ + color: #d9d9d9; +} diff --git a/doc/_static/css/user.css b/doc/_static/css/user.css new file mode 100644 index 000000000..6b3b9c973 --- /dev/null +++ b/doc/_static/css/user.css @@ -0,0 +1,38 @@ +/* SPDX-License-Identifier: GPL-3.0-or-later */ + +.wy-side-nav-search { + background-color: #00a2e2; /* From logo manual */ +} +.wy-side-nav-search input[type=text] { + border-color: #45bfff; +} +.wy-side-nav-search div.version { + color: hsla(0,0%,100%,0.4); +} +.wy-nav-top { + background-color: #00a2e2; +} + +a { + color: #00619c; +} +a:hover { + color: #00a2e2; +} +a:visited { + color: #00619c; +} +a:visited:hover { + color: #00a2e2; +} + +.wy-menu-vertical p.caption { + color: #00a2e2; +} + +.wy-menu-vertical a, .wy-menu-vertical a:hover, .wy-menu-vertical a:visited, +.wy-menu-vertical a:visited:hover { + /* This is here so that the a-rules above do not override the menu colors, + * which should remain grey */ + color: #d9d9d9; +} diff --git a/doc/_static/logo-negativ-dev.svg b/doc/_static/logo-negativ-dev.svg new file mode 100644 index 000000000..5bd4b771e --- /dev/null +++ b/doc/_static/logo-negativ-dev.svg @@ -0,0 +1,36 @@ + + + + + + + + + + + + diff --git a/doc/config-dnssec-glue.rst b/doc/config-dnssec-glue.rst deleted file mode 100644 index 9728cfbc2..000000000 --- a/doc/config-dnssec-glue.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. SPDX-License-Identifier: GPL-3.0-or-later - -.. option:: options/glue-checking: normal|strict|permissive - - :default: normal - - The resolver strictness checking level. - - By default, resolver runs in *normal* mode. There are possibly many small adjustments - hidden behind the mode settings, but the main idea is that in *permissive* mode, the resolver - tries to resolve a name with as few lookups as possible, while in *strict* mode it spends much - more effort resolving and checking referral path. However, if majority of the traffic is covered - by DNSSEC, some of the strict checking actions are counter-productive. - - .. csv-table:: - :header: "Glue type", "Modes when it is accepted", "Example glue [#example_glue]_" - - "mandatory glue", "strict, normal, permissive", "ns1.example.org" - "in-bailiwick glue", "normal, permissive", "ns1.example2.org" - "any glue records", "permissive", "ns1.example3.net" - - .. [#example_glue] The examples show glue records acceptable from servers - authoritative for `org` zone when delegating to `example.org` zone. - Unacceptable or missing glue records trigger resolution of names listed - in NS records before following respective delegation. diff --git a/doc/config-dnssec.rst b/doc/config-dnssec.rst deleted file mode 100644 index 3f9e3ad99..000000000 --- a/doc/config-dnssec.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. SPDX-License-Identifier: GPL-3.0-or-later - -.. _config-dnssec: - -************************* -DNSSEC, data verification -************************* - -Good news! Knot Resolver uses secure configuration by default, and this configuration -should not be changed unless absolutely necessary, so feel free to skip over this section. - -.. include:: config-dnssec-ta.rst - -DNSSEC is main technology to protect data, but it is also possible to change how strictly -resolver checks data from insecure DNS zones: - -.. include:: config-dnssec-glue.rst diff --git a/doc/config-logging-header.rst b/doc/config-logging-header.rst deleted file mode 100644 index 551b1bec2..000000000 --- a/doc/config-logging-header.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. SPDX-License-Identifier: GPL-3.0-or-later - -Logging API -=========== - -.. _config_log_groups: - -.. doxygenfile:: lib/log.h - :project: libkres diff --git a/doc/config-network-forwarding.rst b/doc/config-network-forwarding.rst deleted file mode 100644 index f8b1ab70f..000000000 --- a/doc/config-network-forwarding.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. SPDX-License-Identifier: GPL-3.0-or-later - -Forwarding ----------- - -*Forwarding* configuration instructs resolver to forward cache-miss queries from clients to manually specified DNS resolvers *(upstream servers)*. -In other words the *forwarding* mode does exact opposite of the default *recursive* mode because resolver in *recursive* mode automatically selects which servers to ask. - -Main use-cases are: - - * Building a tree structure of DNS resolvers to improve performance (by improving cache hit rate). - * Accessing domains which are not available using recursion (e.g. if internal company servers return different answers than public ones). - * Forwarding through a central DNS traffic filter. - -Forwarding implementation in Knot Resolver has following properties: - - * Answers from *upstream* servers are cached. - * Answers from *upstream* servers are locally DNSSEC-validated, unless dnssec is disabled. - * Resolver automatically selects which IP address from given set of IP addresses will be used (based on performance characteristics). - * :ref:`Forwarding ` can use either encrypted or unencrypted DNS protocol. - -.. warning:: - - We strongly discourage use of "fake top-level domains" like ``corp.`` because these made-up domains are indistinguishable from an attack, so DNSSEC validation will prevent such domains from working. - If you *really* need a variant of forwarding which does not DNSSEC-validate received data please see chapter :ref:`dns-graft`. - In long-term it is better to migrate data into a legitimate, properly delegated domains which do not suffer from these security problems. - - -Simple examples for **unencrypted** forwarding: - -.. code-block:: yaml - - forward: - # forward all traffic to specified IP addresses (selected automatically) - - subtree: "." - servers: [2001:db8::1, 192.0.2.1] - # forward only queries for names under domain example.com to a single IP address - - subtree: example.com. - servers: [192.0.2.1] - -To configure encrypted version please see chapter about :ref:`forwarding `. - -Forwarding is documented in depth together with rest of :ref:`config-policy-new`. diff --git a/doc/daemon-bindings-cache.rst b/doc/daemon-bindings-cache.rst deleted file mode 120000 index d5d3ee7b3..000000000 --- a/doc/daemon-bindings-cache.rst +++ /dev/null @@ -1 +0,0 @@ -../daemon/bindings/cache.rst \ No newline at end of file diff --git a/doc/daemon-bindings-net_client.rst b/doc/daemon-bindings-net_client.rst deleted file mode 120000 index c96fc76f4..000000000 --- a/doc/daemon-bindings-net_client.rst +++ /dev/null @@ -1 +0,0 @@ -../daemon/bindings/net_client.rst \ No newline at end of file diff --git a/doc/daemon-bindings-net_dns_tweaks.rst b/doc/daemon-bindings-net_dns_tweaks.rst deleted file mode 120000 index ee7e98ac9..000000000 --- a/doc/daemon-bindings-net_dns_tweaks.rst +++ /dev/null @@ -1 +0,0 @@ -../daemon/bindings/net_dns_tweaks.rst \ No newline at end of file diff --git a/doc/daemon-bindings-net_server.rst b/doc/daemon-bindings-net_server.rst deleted file mode 120000 index b6cf46ce8..000000000 --- a/doc/daemon-bindings-net_server.rst +++ /dev/null @@ -1 +0,0 @@ -../daemon/bindings/net_server.rst \ No newline at end of file diff --git a/doc/daemon-bindings-net_tlssrv.rst b/doc/daemon-bindings-net_tlssrv.rst deleted file mode 120000 index 2e38daa36..000000000 --- a/doc/daemon-bindings-net_tlssrv.rst +++ /dev/null @@ -1 +0,0 @@ -../daemon/bindings/net_tlssrv.rst \ No newline at end of file diff --git a/doc/daemon-bindings-net_xdpsrv.rst b/doc/daemon-bindings-net_xdpsrv.rst deleted file mode 120000 index da7870b25..000000000 --- a/doc/daemon-bindings-net_xdpsrv.rst +++ /dev/null @@ -1 +0,0 @@ -../daemon/bindings/net_xdpsrv.rst \ No newline at end of file diff --git a/doc/daemon-bindings-worker.rst b/doc/daemon-bindings-worker.rst deleted file mode 120000 index 3ea3e6166..000000000 --- a/doc/daemon-bindings-worker.rst +++ /dev/null @@ -1 +0,0 @@ -../daemon/bindings/worker.rst \ No newline at end of file diff --git a/doc/daemon-scripting.rst b/doc/daemon-scripting.rst deleted file mode 120000 index 482b759e3..000000000 --- a/doc/daemon-scripting.rst +++ /dev/null @@ -1 +0,0 @@ -../daemon/scripting.rst \ No newline at end of file diff --git a/doc/Doxyfile b/doc/dev/Doxyfile similarity index 94% rename from doc/Doxyfile rename to doc/dev/Doxyfile index d2f4c5bfb..bb88c1ac4 100644 --- a/doc/Doxyfile +++ b/doc/dev/Doxyfile @@ -6,7 +6,7 @@ GENERATE_LATEX = NO GENERATE_MAN = NO GENERATE_RTF = NO CASE_SENSE_NAMES = NO -INPUT = ../lib ../daemon +INPUT = ../../lib ../../daemon FILE_PATTERNS = *.h QUIET = YES RECURSIVE = YES diff --git a/doc/architecture-gc.rst b/doc/dev/architecture-gc.rst similarity index 100% rename from doc/architecture-gc.rst rename to doc/dev/architecture-gc.rst diff --git a/doc/architecture-kresd.rst b/doc/dev/architecture-kresd.rst similarity index 100% rename from doc/architecture-kresd.rst rename to doc/dev/architecture-kresd.rst diff --git a/doc/architecture-manager.rst b/doc/dev/architecture-manager.rst similarity index 99% rename from doc/architecture-manager.rst rename to doc/dev/architecture-manager.rst index bf663eddf..1a0381af4 100644 --- a/doc/architecture-manager.rst +++ b/doc/dev/architecture-manager.rst @@ -9,7 +9,7 @@ The manager is a component written in Python and a bit of C used for native exte The manager is mostly modelled around config processing pipeline: -.. image:: architecture-manager.svg +.. image:: ../architecture-config.svg :width: 100% :alt: Diagram showing a configuration change request processing pipeline inside of the manager. The request goes first through an API server, then through parsing, validation and normalization steps, then into an actual system manager, which commands supervisord and other system components such as kresd. diff --git a/doc/architecture.rst b/doc/dev/architecture.rst similarity index 98% rename from doc/architecture.rst rename to doc/dev/architecture.rst index dc4dc8625..ba281f9d3 100644 --- a/doc/architecture.rst +++ b/doc/dev/architecture.rst @@ -4,7 +4,7 @@ System architecture Knot Resolver is split into several components, namely the manager, ``kresd`` and the garbage collector. In addition to these custom components, we also rely on `supervisord `_. -.. image:: architecture-schema.svg +.. image:: architecture-supervisor.svg :width: 100% :alt: Diagram showing process tree and contol relationship between Knot Resolver components. Supervisord is a parent to all processes, namely manager, kresd instances and gc. Manager on the other hand controls every other component and what it does. diff --git a/doc/build.rst b/doc/dev/build.rst similarity index 98% rename from doc/build.rst rename to doc/dev/build.rst index 5b3ca6249..93242195e 100644 --- a/doc/build.rst +++ b/doc/dev/build.rst @@ -2,8 +2,9 @@ .. _build: -Building from sources -===================== +****************** +Cloning repository +****************** .. note:: Latest up-to-date packages for various distribution can be obtained from web ``_. @@ -18,8 +19,9 @@ Beware that some 64-bit systems with LuaJIT 2.1 may be affected by $ git clone --recursive https://gitlab.nic.cz/knot/knot-resolver.git +****************** Building with apkg ------------------- +****************** Knot Resolver uses `apkg tool `_ for upstream packaging. It allows build packages localy for supported distributions, which it then installs. @@ -59,8 +61,9 @@ When ``apkg`` is ready, a package can be built and installed. After that Knot Resolver should be installed. +******************* Building with Meson -------------------- +******************* Knot Resolver uses `Meson Build system `_. Shell snippets below should be sufficient for basic usage @@ -69,7 +72,7 @@ article `Using Meson `_. Dependencies -~~~~~~~~~~~~ +============ .. note:: This section lists basic requirements. Individual modules might have additional build or runtime dependencies. @@ -158,7 +161,7 @@ here's an overview for several platforms. * **Mac OS X** - the dependencies can be obtained from `Homebrew formula `_. Compilation -~~~~~~~~~~~ +=========== Folowing meson command creates new build directory named ``build_dir``, configures installation path to ``/tmp/kr`` and enables static build (to allow installation to non-standard path). You can also configure some :ref:`build-options`, in this case enable ``manager``, which is disabled by default. @@ -186,7 +189,7 @@ At this point you can execute the newly installed binary using path ``/tmp/kr/sb .. _build-options: Build options -~~~~~~~~~~~~~ +============= It's possible to change the compilation with build options. These are useful to packagers or developers who wish to customize the daemon behaviour, run @@ -216,7 +219,7 @@ a build directory: .. _build-custom-flags: Customizing compiler flags -~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------- If you'd like to use customize the build, see meson's `built-in options `_. For hardening, see ``b_pie``. @@ -230,7 +233,7 @@ command. .. _build-html-doc: Documentation -------------- +============= To check for documentation dependencies and allow its installation, use ``-Ddoc=enabled``. The documentation doesn't build automatically. Instead, @@ -242,7 +245,7 @@ target ``doc`` must be called explicitly. $ ninja -C build_dir doc Tarball -------- +======= Released tarballs are available from ``_ @@ -261,7 +264,7 @@ It's also possible to make a development snapshot tarball: .. _packaging: Packaging ---------- +========= Recommended build options for packagers: @@ -276,7 +279,7 @@ Recommended build options for packagers: * ``-Dunit_tests=enabled`` to force build of unit tests Systemd -~~~~~~~ +------- It's recommended to use the upstream system unit files. If any customizations are required, drop-in files should be used, instead of patching/changing the @@ -292,7 +295,7 @@ To support enabling services after boot, you must also link ``kresd.target`` to ln -s ../kresd.target /usr/lib/systemd/system/multi-user.target.wants/kresd.target Trust anchors -~~~~~~~~~~~~~ +------------- If the target distro has externally managed (read-only) DNSSEC trust anchors or root hints use this: @@ -305,8 +308,9 @@ In case you want to have automatically managed DNSSEC trust anchors instead, set ``-Dmanaged_ta=enabled`` and make sure both ``keyfile_default`` file and its parent directories are writable by kresd process (after package installation!). +************ Docker image ------------- +************ Visit `hub.docker.com/r/cznic/knot-resolver `_ for instructions how to run @@ -318,7 +322,6 @@ For development, it's possible to build the container directly from your git tre $ docker build -t knot-resolver . - .. _jemalloc: https://jemalloc.net .. _libuv: https://github.com/libuv/libuv .. _LuaJIT: http://luajit.org/luajit.html diff --git a/doc/conf.py b/doc/dev/conf.py similarity index 94% rename from doc/conf.py rename to doc/dev/conf.py index 52db3a72a..3960e5440 100644 --- a/doc/conf.py +++ b/doc/dev/conf.py @@ -16,7 +16,6 @@ if os.environ.get('READTHEDOCS', None) == 'True': extensions = [ 'sphinx.ext.todo', 'sphinx.ext.viewcode', - 'sphinx_tabs.tabs', 'breathe', ] @@ -36,7 +35,7 @@ master_doc = 'index' # General information about the project. project = u'Knot Resolver' copyright = u'CZ.NIC labs' -with open('../meson.build') as f: +with open('../../meson.build') as f: for line in f: match = re.match(r"\s*version\s*:\s*'([^']+)'.*", line) if match is not None: @@ -57,7 +56,7 @@ primary_domain = 'py' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ['../_static'] # Output file base name for HTML help builder. htmlhelp_basename = 'apidoc' @@ -72,9 +71,11 @@ html_theme_options = { 'collapse_navigation': False, 'sticky_navigation': True, } -html_logo = '_static/logo-negativ.svg' -html_style = 'css/main.css' - +html_logo = '../_static/logo-negativ-dev.svg' +html_css_files = [ + 'css/custom.css', + 'css/dev.css', +] # -- Options for LaTeX output -------------------------------------------------- # Grouping the document tree into LaTeX files. List of tuples diff --git a/doc/config-answer-reordering.rst b/doc/dev/config-answer-reordering.rst similarity index 100% rename from doc/config-answer-reordering.rst rename to doc/dev/config-answer-reordering.rst diff --git a/doc/config-lua-dnssec.rst b/doc/dev/config-lua-dnssec.rst similarity index 84% rename from doc/config-lua-dnssec.rst rename to doc/dev/config-lua-dnssec.rst index f20e2b30c..7be496301 100644 --- a/doc/config-lua-dnssec.rst +++ b/doc/dev/config-lua-dnssec.rst @@ -9,9 +9,9 @@ DNSSEC, data verification Good news! Knot Resolver uses secure configuration by default, and this configuration should not be changed unless absolutely necessary, so feel free to skip over this section. -.. include:: ../daemon/lua/trust_anchors.rst +.. include:: ../../daemon/lua/trust_anchors.rst DNSSEC is main technology to protect data, but it is also possible to change how strictly resolver checks data from insecure DNS zones: -.. include:: ../lib/layer/mode.rst +.. include:: ../../lib/layer/mode.rst diff --git a/doc/config-lua-experimental.rst b/doc/dev/config-lua-experimental.rst similarity index 100% rename from doc/config-lua-experimental.rst rename to doc/dev/config-lua-experimental.rst diff --git a/doc/config-lua-logging-monitoring.rst b/doc/dev/config-lua-logging-monitoring.rst similarity index 100% rename from doc/config-lua-logging-monitoring.rst rename to doc/dev/config-lua-logging-monitoring.rst diff --git a/doc/config-lua-network.rst b/doc/dev/config-lua-network.rst similarity index 98% rename from doc/config-lua-network.rst rename to doc/dev/config-lua-network.rst index c96bbf8a4..8bd67eefb 100644 --- a/doc/config-lua-network.rst +++ b/doc/dev/config-lua-network.rst @@ -15,7 +15,7 @@ This picture illustrates different actors involved DNS resolution process, supported protocols, and clarifies what we call *server configuration* and *client configuration*. -.. image:: server_terminology.svg +.. image:: ../server_terminology.svg *Attribution: Icons by Bernar Novalyi from the Noun Project* diff --git a/doc/config-lua-overview.rst b/doc/dev/config-lua-overview.rst similarity index 98% rename from doc/config-lua-overview.rst rename to doc/dev/config-lua-overview.rst index cd7f90863..c710f90ac 100644 --- a/doc/config-lua-overview.rst +++ b/doc/dev/config-lua-overview.rst @@ -82,7 +82,7 @@ Following example demonstrates how to interactively list all currently loaded mo Before we dive into configuring features, let us explain modularization basics. -.. include:: ../daemon/bindings/modules.rst +.. 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! diff --git a/doc/config-lua-performance.rst b/doc/dev/config-lua-performance.rst similarity index 100% rename from doc/config-lua-performance.rst rename to doc/dev/config-lua-performance.rst diff --git a/doc/config-lua-policy.rst b/doc/dev/config-lua-policy.rst similarity index 100% rename from doc/config-lua-policy.rst rename to doc/dev/config-lua-policy.rst diff --git a/doc/dev/daemon-bindings-cache.rst b/doc/dev/daemon-bindings-cache.rst new file mode 120000 index 000000000..99af6dfad --- /dev/null +++ b/doc/dev/daemon-bindings-cache.rst @@ -0,0 +1 @@ +../../daemon/bindings/cache.rst \ No newline at end of file diff --git a/doc/dev/daemon-bindings-net_client.rst b/doc/dev/daemon-bindings-net_client.rst new file mode 120000 index 000000000..1a4e688c4 --- /dev/null +++ b/doc/dev/daemon-bindings-net_client.rst @@ -0,0 +1 @@ +../../daemon/bindings/net_client.rst \ No newline at end of file diff --git a/doc/dev/daemon-bindings-net_dns_tweaks.rst b/doc/dev/daemon-bindings-net_dns_tweaks.rst new file mode 120000 index 000000000..223686e29 --- /dev/null +++ b/doc/dev/daemon-bindings-net_dns_tweaks.rst @@ -0,0 +1 @@ +../../daemon/bindings/net_dns_tweaks.rst \ No newline at end of file diff --git a/doc/dev/daemon-bindings-net_server.rst b/doc/dev/daemon-bindings-net_server.rst new file mode 120000 index 000000000..b8eb02591 --- /dev/null +++ b/doc/dev/daemon-bindings-net_server.rst @@ -0,0 +1 @@ +../../daemon/bindings/net_server.rst \ No newline at end of file diff --git a/doc/dev/daemon-bindings-net_tlssrv.rst b/doc/dev/daemon-bindings-net_tlssrv.rst new file mode 120000 index 000000000..4b2af0f8d --- /dev/null +++ b/doc/dev/daemon-bindings-net_tlssrv.rst @@ -0,0 +1 @@ +../../daemon/bindings/net_tlssrv.rst \ No newline at end of file diff --git a/doc/dev/daemon-bindings-net_xdpsrv.rst b/doc/dev/daemon-bindings-net_xdpsrv.rst new file mode 120000 index 000000000..e92e0cacc --- /dev/null +++ b/doc/dev/daemon-bindings-net_xdpsrv.rst @@ -0,0 +1 @@ +../../daemon/bindings/net_xdpsrv.rst \ No newline at end of file diff --git a/doc/dev/daemon-bindings-worker.rst b/doc/dev/daemon-bindings-worker.rst new file mode 120000 index 000000000..f54f2da09 --- /dev/null +++ b/doc/dev/daemon-bindings-worker.rst @@ -0,0 +1 @@ +../../daemon/bindings/worker.rst \ No newline at end of file diff --git a/doc/dev/daemon-scripting.rst b/doc/dev/daemon-scripting.rst new file mode 120000 index 000000000..c8ba7ea5f --- /dev/null +++ b/doc/dev/daemon-scripting.rst @@ -0,0 +1 @@ +../../daemon/scripting.rst \ No newline at end of file diff --git a/doc/flowcharts/io_and_worker.dia b/doc/dev/flowcharts/io_and_worker.dia similarity index 100% rename from doc/flowcharts/io_and_worker.dia rename to doc/dev/flowcharts/io_and_worker.dia diff --git a/doc/flowcharts/task_ERD.dia b/doc/dev/flowcharts/task_ERD.dia similarity index 100% rename from doc/flowcharts/task_ERD.dia rename to doc/dev/flowcharts/task_ERD.dia diff --git a/doc/flowcharts/tcp_task.dia b/doc/dev/flowcharts/tcp_task.dia similarity index 100% rename from doc/flowcharts/tcp_task.dia rename to doc/dev/flowcharts/tcp_task.dia diff --git a/doc/flowcharts/udp_task.dia b/doc/dev/flowcharts/udp_task.dia similarity index 100% rename from doc/flowcharts/udp_task.dia rename to doc/dev/flowcharts/udp_task.dia diff --git a/doc/dev/index.rst b/doc/dev/index.rst new file mode 100644 index 000000000..d8e89aae5 --- /dev/null +++ b/doc/dev/index.rst @@ -0,0 +1,53 @@ +.. SPDX-License-Identifier: GPL-3.0-or-later + +############# +Knot Resolver +############# + +Welcome to Knot Resolver's documentation for developers and advanced users! + +.. toctree:: + :caption: Building for sources + :name: build-chapter + :maxdepth: 1 + + build + +.. toctree:: + :caption: Lua configuration + :name: configuration-lua-chapter + :maxdepth: 1 + + config-lua-overview + config-lua-network + config-lua-performance + config-lua-policy + config-lua-logging-monitoring + config-lua-dnssec + config-lua-experimental + modules-http-custom-services + +.. toctree:: + :caption: Modules and worker API, Lib + :name: configuration-lua-chapter + :maxdepth: 1 + + lib + modules_api + worker_api + +.. toctree:: + :caption: Architecture + :name: architecture-chapter + :maxdepth: 1 + + manager-dev + architecture + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/lib.rst b/doc/dev/lib.rst similarity index 97% rename from doc/lib.rst rename to doc/dev/lib.rst index 096afb643..2378f5668 100644 --- a/doc/lib.rst +++ b/doc/dev/lib.rst @@ -2,7 +2,7 @@ .. _lib_index: -.. include:: ../lib/README.rst +.. include:: ../../lib/README.rst API reference ============= diff --git a/doc/manager-dev.rst b/doc/dev/manager-dev.rst similarity index 100% rename from doc/manager-dev.rst rename to doc/dev/manager-dev.rst diff --git a/doc/dev/modules-bogus_log.rst b/doc/dev/modules-bogus_log.rst new file mode 120000 index 000000000..6d98f43ff --- /dev/null +++ b/doc/dev/modules-bogus_log.rst @@ -0,0 +1 @@ +../../modules/bogus_log/README.rst \ No newline at end of file diff --git a/doc/dev/modules-daf.rst b/doc/dev/modules-daf.rst new file mode 120000 index 000000000..d91d699bd --- /dev/null +++ b/doc/dev/modules-daf.rst @@ -0,0 +1 @@ +../../modules/daf/README.rst \ No newline at end of file diff --git a/doc/dev/modules-detect_time_jump.rst b/doc/dev/modules-detect_time_jump.rst new file mode 120000 index 000000000..8b4150ffc --- /dev/null +++ b/doc/dev/modules-detect_time_jump.rst @@ -0,0 +1 @@ +../../modules/detect_time_jump/README.rst \ No newline at end of file diff --git a/doc/dev/modules-detect_time_skew.rst b/doc/dev/modules-detect_time_skew.rst new file mode 120000 index 000000000..67f7bf545 --- /dev/null +++ b/doc/dev/modules-detect_time_skew.rst @@ -0,0 +1 @@ +../../modules/detect_time_skew/README.rst \ No newline at end of file diff --git a/doc/dev/modules-dns64.rst b/doc/dev/modules-dns64.rst new file mode 120000 index 000000000..374a1b95f --- /dev/null +++ b/doc/dev/modules-dns64.rst @@ -0,0 +1 @@ +../../modules/dns64/README.rst \ No newline at end of file diff --git a/doc/dev/modules-dnstap.rst b/doc/dev/modules-dnstap.rst new file mode 120000 index 000000000..a284f204b --- /dev/null +++ b/doc/dev/modules-dnstap.rst @@ -0,0 +1 @@ +../../modules/dnstap/README.rst \ No newline at end of file diff --git a/doc/dev/modules-edns_keepalive.rst b/doc/dev/modules-edns_keepalive.rst new file mode 120000 index 000000000..91307a4f0 --- /dev/null +++ b/doc/dev/modules-edns_keepalive.rst @@ -0,0 +1 @@ +../../modules/edns_keepalive/README.rst \ No newline at end of file diff --git a/doc/dev/modules-experimental_dot_auth.rst b/doc/dev/modules-experimental_dot_auth.rst new file mode 120000 index 000000000..677cb1e65 --- /dev/null +++ b/doc/dev/modules-experimental_dot_auth.rst @@ -0,0 +1 @@ +../../modules/experimental_dot_auth/README.rst \ No newline at end of file diff --git a/doc/dev/modules-hints.rst b/doc/dev/modules-hints.rst new file mode 120000 index 000000000..a67befde1 --- /dev/null +++ b/doc/dev/modules-hints.rst @@ -0,0 +1 @@ +../../modules/hints/README.rst \ No newline at end of file diff --git a/doc/dev/modules-http-custom-services.rst b/doc/dev/modules-http-custom-services.rst new file mode 120000 index 000000000..223b22d46 --- /dev/null +++ b/doc/dev/modules-http-custom-services.rst @@ -0,0 +1 @@ +../../modules/http/custom_services.rst \ No newline at end of file diff --git a/doc/dev/modules-http-trace.rst b/doc/dev/modules-http-trace.rst new file mode 120000 index 000000000..1c4f666c1 --- /dev/null +++ b/doc/dev/modules-http-trace.rst @@ -0,0 +1 @@ +../../modules/http/trace.rst \ No newline at end of file diff --git a/doc/dev/modules-http.rst b/doc/dev/modules-http.rst new file mode 120000 index 000000000..9713c5e72 --- /dev/null +++ b/doc/dev/modules-http.rst @@ -0,0 +1 @@ +../../modules/http/README.rst \ No newline at end of file diff --git a/doc/dev/modules-nsid.rst b/doc/dev/modules-nsid.rst new file mode 120000 index 000000000..349fabd1e --- /dev/null +++ b/doc/dev/modules-nsid.rst @@ -0,0 +1 @@ +../../modules/nsid/README.rst \ No newline at end of file diff --git a/doc/dev/modules-policy.rst b/doc/dev/modules-policy.rst new file mode 120000 index 000000000..5a9a1edbf --- /dev/null +++ b/doc/dev/modules-policy.rst @@ -0,0 +1 @@ +../../modules/policy/README.rst \ No newline at end of file diff --git a/doc/dev/modules-predict.rst b/doc/dev/modules-predict.rst new file mode 120000 index 000000000..f60ef143b --- /dev/null +++ b/doc/dev/modules-predict.rst @@ -0,0 +1 @@ +../../modules/predict/README.rst \ No newline at end of file diff --git a/doc/dev/modules-prefill.rst b/doc/dev/modules-prefill.rst new file mode 120000 index 000000000..33cac078a --- /dev/null +++ b/doc/dev/modules-prefill.rst @@ -0,0 +1 @@ +../../modules/prefill/README.rst \ No newline at end of file diff --git a/doc/dev/modules-priming.rst b/doc/dev/modules-priming.rst new file mode 120000 index 000000000..738f810e0 --- /dev/null +++ b/doc/dev/modules-priming.rst @@ -0,0 +1 @@ +../../modules/priming/README.rst \ No newline at end of file diff --git a/doc/dev/modules-rebinding.rst b/doc/dev/modules-rebinding.rst new file mode 120000 index 000000000..f8b05dad4 --- /dev/null +++ b/doc/dev/modules-rebinding.rst @@ -0,0 +1 @@ +../../modules/rebinding/README.rst \ No newline at end of file diff --git a/doc/dev/modules-refuse_nord.rst b/doc/dev/modules-refuse_nord.rst new file mode 120000 index 000000000..4713ba5cc --- /dev/null +++ b/doc/dev/modules-refuse_nord.rst @@ -0,0 +1 @@ +../../modules/refuse_nord/README.rst \ No newline at end of file diff --git a/doc/dev/modules-renumber.rst b/doc/dev/modules-renumber.rst new file mode 120000 index 000000000..c413055e8 --- /dev/null +++ b/doc/dev/modules-renumber.rst @@ -0,0 +1 @@ +../../modules/renumber/README.rst \ No newline at end of file diff --git a/doc/dev/modules-rfc7706.rst b/doc/dev/modules-rfc7706.rst new file mode 120000 index 000000000..27a0c7072 --- /dev/null +++ b/doc/dev/modules-rfc7706.rst @@ -0,0 +1 @@ +../../modules/rfc7706.rst \ No newline at end of file diff --git a/doc/dev/modules-serve_stale.rst b/doc/dev/modules-serve_stale.rst new file mode 120000 index 000000000..6a37d0dbf --- /dev/null +++ b/doc/dev/modules-serve_stale.rst @@ -0,0 +1 @@ +../../modules/serve_stale/README.rst \ No newline at end of file diff --git a/doc/dev/modules-stats.rst b/doc/dev/modules-stats.rst new file mode 120000 index 000000000..b65f2952b --- /dev/null +++ b/doc/dev/modules-stats.rst @@ -0,0 +1 @@ +../../modules/stats/README.rst \ No newline at end of file diff --git a/doc/dev/modules-ta_sentinel.rst b/doc/dev/modules-ta_sentinel.rst new file mode 120000 index 000000000..ab255d755 --- /dev/null +++ b/doc/dev/modules-ta_sentinel.rst @@ -0,0 +1 @@ +../../modules/ta_sentinel/README.rst \ No newline at end of file diff --git a/doc/dev/modules-ta_signal_query.rst b/doc/dev/modules-ta_signal_query.rst new file mode 120000 index 000000000..e0d6929a8 --- /dev/null +++ b/doc/dev/modules-ta_signal_query.rst @@ -0,0 +1 @@ +../../modules/ta_signal_query/README.rst \ No newline at end of file diff --git a/doc/dev/modules-view.rst b/doc/dev/modules-view.rst new file mode 120000 index 000000000..048f41460 --- /dev/null +++ b/doc/dev/modules-view.rst @@ -0,0 +1 @@ +../../modules/view/README.rst \ No newline at end of file diff --git a/doc/dev/modules-watchdog.rst b/doc/dev/modules-watchdog.rst new file mode 120000 index 000000000..648513a4a --- /dev/null +++ b/doc/dev/modules-watchdog.rst @@ -0,0 +1 @@ +../../modules/watchdog/README.rst \ No newline at end of file diff --git a/doc/modules_api.rst b/doc/dev/modules_api.rst similarity index 61% rename from doc/modules_api.rst rename to doc/dev/modules_api.rst index 05f7407fb..ea23a3e24 100644 --- a/doc/modules_api.rst +++ b/doc/dev/modules_api.rst @@ -2,5 +2,5 @@ .. _modules: -.. include:: ../modules/README.rst +.. include:: ../../modules/README.rst diff --git a/doc/dev/rename_ln.sh b/doc/dev/rename_ln.sh new file mode 100644 index 000000000..4dd26469f --- /dev/null +++ b/doc/dev/rename_ln.sh @@ -0,0 +1,9 @@ + +for name in $(find . -type l -name "modules-*"); do + tgt=`readlink "$name"` + ln -f -s ../$tgt $name +done + + + + diff --git a/doc/server_terminology.fodg b/doc/dev/server_terminology.fodg similarity index 100% rename from doc/server_terminology.fodg rename to doc/dev/server_terminology.fodg diff --git a/doc/dev/systemd-multiinst.rst b/doc/dev/systemd-multiinst.rst new file mode 120000 index 000000000..7a6a86a45 --- /dev/null +++ b/doc/dev/systemd-multiinst.rst @@ -0,0 +1 @@ +../../systemd/multiinst.rst \ No newline at end of file diff --git a/doc/worker_api.rst b/doc/dev/worker_api.rst similarity index 100% rename from doc/worker_api.rst rename to doc/dev/worker_api.rst diff --git a/doc/internal-lua-config.rst b/doc/internal-lua-config.rst deleted file mode 100644 index 95d79c17d..000000000 --- a/doc/internal-lua-config.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. SPDX-License-Identifier: GPL-3.0-or-later - -.. _internal-lua-config: - -************************** -Internal Lua configuration -************************** - -.. toctree:: - :maxdepth: 2 - - config-lua-overview - config-lua-network - config-lua-performance - config-lua-policy - config-lua-logging-monitoring - config-lua-dnssec - config-lua-experimental diff --git a/doc/modules-bogus_log.rst b/doc/modules-bogus_log.rst deleted file mode 120000 index 61ead5009..000000000 --- a/doc/modules-bogus_log.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/bogus_log/README.rst \ No newline at end of file diff --git a/doc/modules-daf.rst b/doc/modules-daf.rst deleted file mode 120000 index 7715ed648..000000000 --- a/doc/modules-daf.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/daf/README.rst \ No newline at end of file diff --git a/doc/modules-detect_time_jump.rst b/doc/modules-detect_time_jump.rst deleted file mode 120000 index 282148225..000000000 --- a/doc/modules-detect_time_jump.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/detect_time_jump/README.rst \ No newline at end of file diff --git a/doc/modules-detect_time_skew.rst b/doc/modules-detect_time_skew.rst deleted file mode 120000 index f0c0d1496..000000000 --- a/doc/modules-detect_time_skew.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/detect_time_skew/README.rst \ No newline at end of file diff --git a/doc/modules-dns64.rst b/doc/modules-dns64.rst deleted file mode 120000 index 792753a77..000000000 --- a/doc/modules-dns64.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/dns64/README.rst \ No newline at end of file diff --git a/doc/modules-dnstap.rst b/doc/modules-dnstap.rst deleted file mode 120000 index f77d78ec2..000000000 --- a/doc/modules-dnstap.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/dnstap/README.rst \ No newline at end of file diff --git a/doc/modules-edns_keepalive.rst b/doc/modules-edns_keepalive.rst deleted file mode 120000 index ec7a3589f..000000000 --- a/doc/modules-edns_keepalive.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/edns_keepalive/README.rst \ No newline at end of file diff --git a/doc/modules-experimental_dot_auth.rst b/doc/modules-experimental_dot_auth.rst deleted file mode 120000 index c5bbfdc51..000000000 --- a/doc/modules-experimental_dot_auth.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/experimental_dot_auth/README.rst \ No newline at end of file diff --git a/doc/modules-hints.rst b/doc/modules-hints.rst deleted file mode 120000 index 16063101f..000000000 --- a/doc/modules-hints.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/hints/README.rst \ No newline at end of file diff --git a/doc/modules-http-custom-services.rst b/doc/modules-http-custom-services.rst deleted file mode 120000 index 5cbc7ec15..000000000 --- a/doc/modules-http-custom-services.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/http/custom_services.rst \ No newline at end of file diff --git a/doc/modules-http-trace.rst b/doc/modules-http-trace.rst deleted file mode 120000 index c11fca0ea..000000000 --- a/doc/modules-http-trace.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/http/trace.rst \ No newline at end of file diff --git a/doc/modules-http.rst b/doc/modules-http.rst deleted file mode 120000 index 3fc5fec36..000000000 --- a/doc/modules-http.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/http/README.rst \ No newline at end of file diff --git a/doc/modules-nsid.rst b/doc/modules-nsid.rst deleted file mode 120000 index 7ea4cc776..000000000 --- a/doc/modules-nsid.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/nsid/README.rst \ No newline at end of file diff --git a/doc/modules-policy.rst b/doc/modules-policy.rst deleted file mode 120000 index 690a2b5d5..000000000 --- a/doc/modules-policy.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/policy/README.rst \ No newline at end of file diff --git a/doc/modules-predict.rst b/doc/modules-predict.rst deleted file mode 120000 index a4a8424ab..000000000 --- a/doc/modules-predict.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/predict/README.rst \ No newline at end of file diff --git a/doc/modules-prefill.rst b/doc/modules-prefill.rst deleted file mode 120000 index cfa8384a7..000000000 --- a/doc/modules-prefill.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/prefill/README.rst \ No newline at end of file diff --git a/doc/modules-priming.rst b/doc/modules-priming.rst deleted file mode 120000 index a36c3bfca..000000000 --- a/doc/modules-priming.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/priming/README.rst \ No newline at end of file diff --git a/doc/modules-rebinding.rst b/doc/modules-rebinding.rst deleted file mode 120000 index a8e9d016e..000000000 --- a/doc/modules-rebinding.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/rebinding/README.rst \ No newline at end of file diff --git a/doc/modules-refuse_nord.rst b/doc/modules-refuse_nord.rst deleted file mode 120000 index 22e585cf8..000000000 --- a/doc/modules-refuse_nord.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/refuse_nord/README.rst \ No newline at end of file diff --git a/doc/modules-renumber.rst b/doc/modules-renumber.rst deleted file mode 120000 index 1764c78a6..000000000 --- a/doc/modules-renumber.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/renumber/README.rst \ No newline at end of file diff --git a/doc/modules-rfc7706.rst b/doc/modules-rfc7706.rst deleted file mode 120000 index 11b5c3d80..000000000 --- a/doc/modules-rfc7706.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/rfc7706.rst \ No newline at end of file diff --git a/doc/modules-serve_stale.rst b/doc/modules-serve_stale.rst deleted file mode 120000 index 98fa53188..000000000 --- a/doc/modules-serve_stale.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/serve_stale/README.rst \ No newline at end of file diff --git a/doc/modules-stats.rst b/doc/modules-stats.rst deleted file mode 120000 index c8c5583ef..000000000 --- a/doc/modules-stats.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/stats/README.rst \ No newline at end of file diff --git a/doc/modules-ta_sentinel.rst b/doc/modules-ta_sentinel.rst deleted file mode 120000 index 669e5a4e3..000000000 --- a/doc/modules-ta_sentinel.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/ta_sentinel/README.rst \ No newline at end of file diff --git a/doc/modules-ta_signal_query.rst b/doc/modules-ta_signal_query.rst deleted file mode 120000 index 15e5d67f6..000000000 --- a/doc/modules-ta_signal_query.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/ta_signal_query/README.rst \ No newline at end of file diff --git a/doc/modules-view.rst b/doc/modules-view.rst deleted file mode 120000 index da228331c..000000000 --- a/doc/modules-view.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/view/README.rst \ No newline at end of file diff --git a/doc/modules-watchdog.rst b/doc/modules-watchdog.rst deleted file mode 120000 index ac7d54779..000000000 --- a/doc/modules-watchdog.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/watchdog/README.rst \ No newline at end of file diff --git a/doc/systemd-multiinst.rst b/doc/systemd-multiinst.rst deleted file mode 120000 index 2f532708b..000000000 --- a/doc/systemd-multiinst.rst +++ /dev/null @@ -1 +0,0 @@ -../systemd/multiinst.rst \ No newline at end of file diff --git a/doc/upgrading.rst b/doc/upgrading.rst deleted file mode 100644 index b41dd7a5a..000000000 --- a/doc/upgrading.rst +++ /dev/null @@ -1,338 +0,0 @@ -.. SPDX-License-Identifier: GPL-3.0-or-later - -.. _upgrading: - -********* -Upgrading -********* - -This section summarizes steps required when upgrading to newer Knot Resolver versions. -We advise users to also read :ref:`release_notes` for respective versions. -Section *Module changes* is relevant only for users who develop or use third-party modules. - - -Upcoming changes -================ - -Following section provides information about selected changes in not-yet-released versions. -We advise users to prepare for these changes sooner rather than later to make it easier to upgrade to -newer versions when they are released. - -* Command line option ``--forks`` (``-f``) `is deprecated and will be eventually removed - `_. - Preferred way to manage :ref:`systemd-multiple-instances` is to use a process manager, - e.g. systemd_ or supervisord_. -* Function :func:`verbose` is deprecated and will be eventually removed. - Prefered way to change logging level is use to :func:`log_level`. - -.. _`systemd`: https://systemd.io/ -.. _`supervisord`: http://supervisord.org/ - - -5.x to 6.x -========== - -* see the more detailed guide for :ref:`upgrading to version 6.x ` - - -5.4 to 5.5 -========== - -Packagers & Developers ----------------------- - -* Knot DNS >= 3.0.2 is required. - -Module API changes ------------------- -* Function `cache.zone_import` was removed; - you can use `ffi.C.zi_zone_import` instead (different API). -* When using :ref:`proxyv2`, the meaning of ``qsource.flags`` and ``qsource.comm_flags`` - in :c:member:`kr_request` changes so that ``flags`` describes the original client - communicating with the proxy, while ``comm_flags`` describes the proxy communicating - with the resolver. When there is no proxy, ``flags`` and ``comm_flags`` are the same. - - -5.3 to 5.4 -========== - -Configuration file ------------------- - -* ``kind='doh'`` in :func:`net.listen` was renamed to ``kind='doh_legacy'``. It is recommended to switch to the new DoH implementation with ``kind='doh2'``. -* :func:`verbose` has been deprecated. In case you want to change logging level, - there is new function :func:`log_level`. - -Packagers & Developers ----------------------- - -* meson option ``verbose_log`` was removed. - -Module changes --------------- - -* lua function ``warn()`` was removed, use ``log_warn()`` instead. The new function takes a log group number as the first argument. -* C functions ``kr_log_req()`` and ``kr_log_q()`` were replaced by ``kr_log_req1()`` and ``kr_log_q1()`` respectively. The new function have slightly different API. - - -5.2 to 5.3 -========== - -Configuration file ------------------- - -* Module ``dnstap``: option ``log_responses`` has been moved inside a new ``client`` section. Refer to the configuration example in :ref:`mod-dnstap`. - -Packagers & Developers ----------------------- - -* Knot DNS >= 2.9 is required. - -5.1 to 5.2 -========== - -Users ------ - -* DoH over HTTP/1 and unencrypted transports is still available in - :ref:`legacy http module ` (``kind='doh'``). - This module will not receive receive any more bugfixes and will be eventually removed. -* Users of :ref:`control-sockets` API need to terminate each command sent to resolver with newline - character (ASCII ``\n``). Correct usage: ``cache.stats()\n``. - Newline terminated commands are accepted by all resolver versions >= 1.0.0. -* `DNS Flag Day 2020 `_ is now effective and Knot Resolver uses - maximum size of UDP answer to 1232 bytes. Please double-check your firewall, - it has to allow DNS traffic on UDP and **also TCP** port 53. -* Human readable output in interactive mode and from :ref:`control-sockets` was improved and - as consequence slightly changed its format. Users who need machine readable output for scripts - should use Lua function ``tojson()`` to convert Lua values into standard JSON format instead - of attempting to parse the human readable output. - For example API call ``tojson(cache.stats())\n`` will return JSON string with ``cache.stats()`` - results represented as dictionary. - Function ``tojson()`` is available in all resolver versions >= 1.0.0. - -Configuration file ------------------- - -* Statistics exporter :ref:`mod-graphite` now uses default prefix which combines - :func:`hostname()` and :envvar:`worker.id` instead of bare :func:`hostname()`. - This prevents :ref:`systemd-multiple-instances` from sending - conflicting statistics to server. In case you want to continue in previous time series you - can manually set the old values using option ``prefix`` - in :ref:`Graphite configuration `. - Beware that non-default values require careful - :ref:`instance-specific-configuration` to avoid conflicting names. -* Lua variable :envvar:`worker.id` is now a string with either Systemd instance name or PID - (instead of number). If your custom configuration uses :envvar:`worker.id` value please - check your scripts. - -Module changes --------------- -* Reply packet :c:type:`kr_request.answer` - `is not allocated `_ - immediately when the request comes. - See the new :c:func:`kr_request_ensure_answer` function, - wrapped for lua as ``req:ensure_answer()``. - - -5.0 to 5.1 -========== - -Module changes --------------- - -* Modules which use :c:type:`kr_request.trace_log` handler need update to modified handler API. Example migration is `modules/watchdog/watchdog.lua `_. -* Modules which were using logger :c:func:`kr_log_qverbose_impl` need migration to new logger :c:func:`kr_log_q`. Example migration is `modules/rebinding/rebinding.lua `_. -* Modules which were using :c:func:`kr_ranked_rrarray_add` should note that on success it no longer returns exclusively zero but index into the array (non-negative). Error states are unchanged (negative). - - -4.x to 5.x -========== - -Users ------ - -* Control socket location has changed - - .. csv-table:: - :header: "","4.x location","5.x location" - - "with systemd","``/run/knot-resolver/control@$ID``","``/run/knot-resolver/control/$ID``" - "without systemd","``$PWD/tty/$PID``","``$PWD/control/$PID``" - -* ``-f`` / ``--forks`` command-line option is deprecated. - In case you just want to trigger non-interactive mode, there's new ``-n`` / ``--noninteractive``. - This forking style `was not ergonomic `_; - with independent kresd processes you can better utilize a process manager (e.g. systemd). - - -Configuration file ------------------- - -* Network interface are now configured in ``kresd.conf`` with - :func:`net.listen` instead of systemd sockets (`#485 - `_). See - the following examples. - - .. tip:: You can find suggested network interface settings based on your - previous systemd socket configuration in - ``/var/lib/knot-resolver/.upgrade-4-to-5/kresd.conf.net`` which is created - during the package update to version 5.x. - - .. csv-table:: - :header: "4.x - systemd socket file", "5.x - kresd.conf" - - "kresd.socket - | [Socket] - | ListenDatagram=127.0.0.1:53 - | ListenStream=127.0.0.1:53","| ``net.listen('127.0.0.1', 53, { kind = 'dns' })``" - "kresd.socket - | [Socket] - | FreeBind=true - | BindIPv6Only=both - | ListenDatagram=[::1]:53 - | ListenStream=[::1]:53 - "," | ``net.listen('127.0.0.1', 53, { kind = 'dns', freebind = true })`` - | ``net.listen('::1', 53, { kind = 'dns', freebind = true })``" - "kresd-tls.socket - | [Socket] - | ListenStream=127.0.0.1:853","| ``net.listen('127.0.0.1', 853, { kind = 'tls' })``" - "kresd-doh.socket - | [Socket] - | ListenStream=127.0.0.1:443","| ``net.listen('127.0.0.1', 443, { kind = 'doh' })``" - "kresd-webmgmt.socket - | [Socket] - | ListenStream=127.0.0.1:8453","| ``net.listen('127.0.0.1', 8453, { kind = 'webmgmt' })``" - -* :func:`net.listen` throws an error if it fails to bind. Use ``freebind=true`` option - to bind to nonlocal addresses. - - -4.2.2 to 4.3+ -============= - -Module changes --------------- - -* In case you wrote your own module which directly calls function - ``kr_ranked_rrarray_add()``, you need to additionally call function - ``kr_ranked_rrarray_finalize()`` after each batch (before changing - the added memory regions). For a specific example see `changes in dns64 module - `_. - -.. _upgrade-from-3-to-4: - -4.x to 4.2.1+ -============= - -Users ------ - -* If you have previously installed ``knot-resolver-dbgsym`` package on Debian, - please remove it and install ``knot-resolver-dbg`` instead. - -3.x to 4.x -========== - -Users ------ - -* DNSSEC validation is now turned on by default. If you need to disable it, see - :ref:`dnssec-config`. -* ``-k/--keyfile`` and ``-K/--keyfile-ro`` daemon options were removed. If needed, - use ``trust_anchors.add_file()`` in configuration file instead. -* Configuration for :ref:`HTTP module ` changed significantly as result of - adding :ref:`mod-http-doh` support. Please see examples below. -* In case you are using your own custom modules, move them to the new module - location. The exact location depends on your distribution. Generally, modules previously - in ``/usr/lib/kdns_modules`` should be moved to ``/usr/lib/knot-resolver/kres_modules``. - -Configuration file -~~~~~~~~~~~~~~~~~~ - -* ``trust_anchors.file``, ``trust_anchors.config()`` and ``trust_anchors.negative`` - aliases were removed to avoid duplicity and confusion. Migration table: - - .. csv-table:: - :header: "3.x configuration", "4.x configuration" - - "``trust_anchors.file = path``", "``trust_anchors.add_file(path)``" - "``trust_anchors.config(path, readonly)``", "``trust_anchors.add_file(path, readonly)``" - "``trust_anchors.negative = nta_set``", "``trust_anchors.set_insecure(nta_set)``" - -* ``trust_anchors.keyfile_default`` is no longer accessible and is can be set - only at compile time. To turn off DNSSEC, use :func:`trust_anchors.remove()`. - - .. csv-table:: - :header: "3.x configuration", "4.x configuration" - - "``trust_anchors.keyfile_default = nil``", "``trust_anchors.remove('.')``" - -* Network for HTTP endpoints is now configured using same mechanism as for normal DNS endpoints, - please refer to chapter :ref:`config-lua-network`. Migration table: - - .. csv-table:: - :header: "3.x configuration", "4.x configuration" - - "``modules = { http = { host = '192.0.2.1', port = 443 }}``","see chapter :ref:`config-lua-network`" - "``http.config({ host = '192.0.2.1', port = 443 })``","see chapter :ref:`config-lua-network`" - "``modules = { http = { endpoints = ... }}``","see chapter :ref:`mod-http-custom-endpoint`" - "``http.config({ endpoints = ... })``","see chapter :ref:`mod-http-custom-endpoint`" - -Packagers & Developers ----------------------- - -* Knot DNS >= 2.8 is required. -* meson >= 0.46 and ninja is required. -* meson build system is now used for compiling the project. For instructions, see - the :ref:`build`. Packagers should pay attention to section :ref:`packaging` - for information about systemd unit files and trust anchors. -* Embedding LMDB is no longer supported, lmdb is now required as an external dependency. -* Trust anchors file from upstream is installed and used as default unless you - override ``keyfile_default`` during build. - -Module changes -~~~~~~~~~~~~~~ - -* Default module location has changed from ``{libdir}/kdns_modules`` to - ``{libdir}/knot-resolver/kres_modules``. Modules are now in the lua namespace - ``kres_modules.*``. -* ``kr_straddr_split()`` API has changed. - -* C modules defining ``*_layer`` or ``*_props`` symbols need to use a different style, but it's typically a trivial change. - Instead of exporting the corresponding symbols, the module should assign pointers to its static structures inside its ``*_init()`` function. Example migration: - `bogus_log module `_. - -.. _upgrade-from-2-to-3: - -2.x to 3.x -========== - -Users ------ - -* Module :ref:`mod-hints` has option :func:`hints.use_nodata` enabled by default, - which is what most users expect. Add ``hints.use_nodata(false)`` to your config - to revert to the old behavior. -* Modules ``cookie`` and ``version`` were removed. - Please remove relevant configuration lines with ``modules.load()`` and ``modules =`` - from configuration file. -* Valid configuration must open cache using ``cache.open()`` or ``cache.size =`` - before executing cache operations like ``cache.clear()``. - (Older versions were silently ignoring such cache operations.) - -Packagers & Developers ----------------------- - -* Knot DNS >= 2.7.2 is required. - -Module changes -~~~~~~~~~~~~~~ - -* API for Lua modules was refactored, please see :ref:`significant-lua-changes`. -* New layer was added: ``answer_finalize``. -* ``kr_request`` keeps ``::qsource.packet`` beyond the ``begin`` layer. -* ``kr_request::qsource.tcp`` renamed to ``::qsource.flags.tcp``. -* ``kr_request::has_tls`` renamed to ``::qsource.flags.tls``. -* ``kr_zonecut_add()``, ``kr_zonecut_del()`` and ``kr_nsrep_sort()`` changed - parameters slightly. diff --git a/doc/NEWS.rst b/doc/user/NEWS.rst similarity index 98% rename from doc/NEWS.rst rename to doc/user/NEWS.rst index 3c84052ad..8a93bc778 100644 --- a/doc/NEWS.rst +++ b/doc/user/NEWS.rst @@ -32,5 +32,5 @@ Patch version This definition is not applicable to versions older than 5.2.0. -.. include:: ../NEWS +.. include:: ../../NEWS :end-before: 5.x branch longterm support diff --git a/doc/user/conf.py b/doc/user/conf.py new file mode 100644 index 000000000..fb2bd287f --- /dev/null +++ b/doc/user/conf.py @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: GPL-3.0-or-later + +import os +import re + +import sphinx_rtd_theme + +# -- General configuration ----------------------------------------------------- + +# General information about the project. +project = u'Knot Resolver' +copyright = u'CZ.NIC labs' +with open('../../meson.build') as f: + for line in f: + match = re.match(r"\s*version\s*:\s*'([^']+)'.*", line) + if match is not None: + version = match.groups()[0] +release = version + +# Add any Sphinx extension module names here, as strings. +extensions = [ + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', + 'sphinx_tabs.tabs', +] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'friendly' + +# -- Options for HTML output --------------------------------------------------- + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['../_static'] + +# Theme +html_theme = 'sphinx_rtd_theme' +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +html_theme_options = { + 'logo_only': True, # if we have a html_logo below, this shows only the logo with no title text + # ToC options + 'collapse_navigation': False, + 'sticky_navigation': True, +} +html_logo = '../_static/logo-negativ.svg' +html_css_files = [ + 'css/custom.css', + 'css/user.css', +] + +# reStructuredText that will be included at the beginning of every source file that is read. +# This is a possible place to add substitutions that should be available in every file. +rst_prolog = """ +.. |yaml| replace:: YAML +.. |lua| replace:: Lua +""" diff --git a/doc/config-cache-predict.rst b/doc/user/config-cache-predict.rst similarity index 100% rename from doc/config-cache-predict.rst rename to doc/user/config-cache-predict.rst diff --git a/doc/config-cache-prefill.rst b/doc/user/config-cache-prefill.rst similarity index 100% rename from doc/config-cache-prefill.rst rename to doc/user/config-cache-prefill.rst diff --git a/doc/config-cache.rst b/doc/user/config-cache.rst similarity index 99% rename from doc/config-cache.rst rename to doc/user/config-cache.rst index 2a0273ff4..66de7da4c 100644 --- a/doc/config-cache.rst +++ b/doc/user/config-cache.rst @@ -223,4 +223,3 @@ Note that the maximum size cannot be lowered, only increased due to how cache is Time interval for which a nameserver address will be ignored after determining that it doesn't return (useful) answers. The intention is to avoid waiting if there's little hope; instead, kresd can immediately SERVFAIL or immediately use stale records (with :ref:`serve-stale `). - diff --git a/doc/config-dns64.rst b/doc/user/config-dns64.rst similarity index 96% rename from doc/config-dns64.rst rename to doc/user/config-dns64.rst index d0c89b283..85c4605e3 100644 --- a/doc/config-dns64.rst +++ b/doc/user/config-dns64.rst @@ -54,7 +54,7 @@ If they appear, they will be replaced by AAAAs generated from As. # You could even pass '::/0' to always force using generated AAAAs. -In case you don't want DNS64 for all clients, you can set ``dns64`` option to ``false`` via the :ref:`views ` section. +In case you don't want DNS64 for all clients, you can set ``dns64`` option to ``false`` via the :ref:`views ` section. .. code-block:: yaml diff --git a/doc/config-dnssec-ta.rst b/doc/user/config-dnssec.rst similarity index 70% rename from doc/config-dnssec-ta.rst rename to doc/user/config-dnssec.rst index b02e2ca7c..d22ee4f2b 100644 --- a/doc/config-dnssec-ta.rst +++ b/doc/user/config-dnssec.rst @@ -1,5 +1,14 @@ .. SPDX-License-Identifier: GPL-3.0-or-later +.. _config-dnssec: + +************************* +DNSSEC, data verification +************************* + +Good news! Knot Resolver uses secure configuration by default, and this configuration +should not be changed unless absolutely necessary, so feel free to skip over this section. + .. warning:: Options in this section are intended only for expert users and normally should not be needed. @@ -104,4 +113,31 @@ Following :option:`dnssec >` section allow to modify DNS trust-anchors: - ". 3600 IN DS 19036 8 2 49AAC11..." +DNSSEC is main technology to protect data, but it is also possible to change how strictly +resolver checks data from insecure DNS zones: + +.. option:: options/glue-checking: normal|strict|permissive + + :default: normal + + The resolver strictness checking level. + + By default, resolver runs in *normal* mode. There are possibly many small adjustments + hidden behind the mode settings, but the main idea is that in *permissive* mode, the resolver + tries to resolve a name with as few lookups as possible, while in *strict* mode it spends much + more effort resolving and checking referral path. However, if majority of the traffic is covered + by DNSSEC, some of the strict checking actions are counter-productive. + + .. csv-table:: + :header: "Glue type", "Modes when it is accepted", "Example glue [#example_glue]_" + + "mandatory glue", "strict, normal, permissive", "ns1.example.org" + "in-bailiwick glue", "normal, permissive", "ns1.example2.org" + "any glue records", "permissive", "ns1.example3.net" + + .. [#example_glue] The examples show glue records acceptable from servers + authoritative for `org` zone when delegating to `example.org` zone. + Unacceptable or missing glue records trigger resolution of names listed + in NS records before following respective delegation. + .. _lua-http: https://luarocks.org/modules/daurnimator/http diff --git a/doc/config-edns-keepalive.rst b/doc/user/config-edns-keepalive.rst similarity index 100% rename from doc/config-edns-keepalive.rst rename to doc/user/config-edns-keepalive.rst diff --git a/doc/config-experimental-dot-auth.rst b/doc/user/config-experimental-dot-auth.rst similarity index 100% rename from doc/config-experimental-dot-auth.rst rename to doc/user/config-experimental-dot-auth.rst diff --git a/doc/config-experimental.rst b/doc/user/config-experimental.rst similarity index 100% rename from doc/config-experimental.rst rename to doc/user/config-experimental.rst diff --git a/doc/config-forward.rst b/doc/user/config-forward.rst similarity index 53% rename from doc/config-forward.rst rename to doc/user/config-forward.rst index 523a3308d..051f7119c 100644 --- a/doc/config-forward.rst +++ b/doc/user/config-forward.rst @@ -5,6 +5,52 @@ Forwarding ========== +*Forwarding* configuration instructs resolver to forward cache-miss queries from clients to manually specified DNS resolvers *(upstream servers)*. +In other words the *forwarding* mode does exact opposite of the default *recursive* mode because resolver in *recursive* mode automatically selects which servers to ask. + +Main use-cases are: + + * Building a tree structure of DNS resolvers to improve performance (by improving cache hit rate). + * Accessing domains which are not available using recursion (e.g. if internal company servers return different answers than public ones). + * Forwarding through a central DNS traffic filter. + +Forwarding implementation in Knot Resolver has following properties: + + * Answers from *upstream* servers are cached. + * Answers from *upstream* servers are locally DNSSEC-validated, unless dnssec is disabled. + * Resolver automatically selects which IP address from given set of IP addresses will be used (based on performance characteristics). + * :ref:`Forwarding ` can use either encrypted or unencrypted DNS protocol. + +.. warning:: + + We strongly discourage use of "fake top-level domains" like ``corp.`` because these made-up domains are indistinguishable from an attack, so DNSSEC validation will prevent such domains from working. + If you *really* need a variant of forwarding which does not DNSSEC-validate received data please see chapter :ref:`dns-graft`. + In long-term it is better to migrate data into a legitimate, properly delegated domains which do not suffer from these security problems. + +.. code-block:: yaml + + forward: + # ask everything through some public resolver + - subtree: . + servers: [ 2001:148f:fffe::1, 193.17.47.1 ] + +.. code-block:: yaml + + forward: + # encrypted public resolver, again for all names + - subtree: . + servers: + - address: [ 2001:148f:fffe::1, 193.17.47.1 ] + transport: tls + hostname: odvr.nic.cz + + # use a local authoritative server for an internal-only zone + - subtree: internal.example.com + servers: [ 10.0.0.53 ] + options: + authoritative: true + dnssec: false + The :option:`forward >` list of rules overrides which servers get asked to obtain DNS data. .. option:: forward: @@ -48,27 +94,3 @@ The :option:`forward >` list of rules overrides which servers ge :default: true Enable/disable DNSSEC for a subtree. - -.. code-block:: yaml - - forward: - # ask everything through some public resolver - - subtree: . - servers: [ 2001:148f:fffe::1, 193.17.47.1 ] - -.. code-block:: yaml - - forward: - # encrypted public resolver, again for all names - - subtree: . - servers: - - address: [ 2001:148f:fffe::1, 193.17.47.1 ] - transport: tls - hostname: odvr.nic.cz - - # use a local authoritative server for an internal-only zone - - subtree: internal.example.com - servers: [ 10.0.0.53 ] - options: - authoritative: true - dnssec: false diff --git a/doc/config-local-data.rst b/doc/user/config-local-data.rst similarity index 100% rename from doc/config-local-data.rst rename to doc/user/config-local-data.rst diff --git a/doc/config-logging-bogus.rst b/doc/user/config-logging-bogus.rst similarity index 100% rename from doc/config-logging-bogus.rst rename to doc/user/config-logging-bogus.rst diff --git a/doc/config-logging-debugging.rst b/doc/user/config-logging-debugging.rst similarity index 100% rename from doc/config-logging-debugging.rst rename to doc/user/config-logging-debugging.rst diff --git a/doc/config-logging-dnstap.rst b/doc/user/config-logging-dnstap.rst similarity index 100% rename from doc/config-logging-dnstap.rst rename to doc/user/config-logging-dnstap.rst diff --git a/doc/config-logging-monitoring.rst b/doc/user/config-logging-monitoring.rst similarity index 81% rename from doc/config-logging-monitoring.rst rename to doc/user/config-logging-monitoring.rst index 5cc80467e..081fac75b 100644 --- a/doc/config-logging-monitoring.rst +++ b/doc/user/config-logging-monitoring.rst @@ -34,8 +34,8 @@ E.g. on distributions using systemd-journald use command ``journalctl -eu knot-r .. option:: groups: - Use to turn-on ``debug`` logging for the selected :ref:`groups ` regardless of the global log level. - Other groups are logged to the log based on the initial level. + Use to turn-on ``debug`` logging for the selected `groups <./dev/config-logging-header.html>`_ + regardless of the global log level. Other groups are logged to the log based on the initial level. .. It is also possible to enable ``debug`` logging level for particular requests, .. with :ref:`policies ` or as :ref:`an HTTP service `. @@ -48,9 +48,12 @@ E.g. on distributions using systemd-journald use command ``journalctl -eu knot-r That setting logs directly through systemd's facilities (if available) to preserve more meta-data. Do not edit if you do not know what you are doing. -Various statistics for monitoring purposes are available in :ref:`config-monitoring-stats`, including export to central systems like Graphite, Metronome, InfluxDB, or Prometheus format. +Various statistics for monitoring purposes are available in :ref:`config-monitoring-stats`, +including export to central systems like Graphite, Metronome, InfluxDB, or Prometheus format. -Additional monitoring and debugging methods are described below. If none of these options fits your deployment or if you have special needs you can configure your own checks and exports using :ref:`async-events`. +Additional monitoring and debugging methods are described below. +If none of these options fits your deployment or if you have special +needs you can configure your own checks and exports using `asynchronous events <./dev/daemon-scripting.html#async-events>`. .. toctree:: :maxdepth: 1 diff --git a/doc/config-lua.rst b/doc/user/config-lua.rst similarity index 100% rename from doc/config-lua.rst rename to doc/user/config-lua.rst diff --git a/doc/config-monitoring-stats.rst b/doc/user/config-monitoring-stats.rst similarity index 96% rename from doc/config-monitoring-stats.rst rename to doc/user/config-monitoring-stats.rst index f86df94c0..43c998700 100644 --- a/doc/config-monitoring-stats.rst +++ b/doc/user/config-monitoring-stats.rst @@ -28,7 +28,7 @@ exposed as :ref:`config-monitoring-prometheus`. * ``lazy`` - Statistics collection is enabled at the time of request. * ``always`` - Statistics collection is always on. -You can see all built-in statistics in :ref:`mod-stats-list` section. +You can see all built-in statistics in `built-in statistics <./dev/modules-stats.html#mod-stats-list>`_ section. .. _config-monitoring-prometheus: diff --git a/doc/config-multiple-workers.rst b/doc/user/config-multiple-workers.rst similarity index 100% rename from doc/config-multiple-workers.rst rename to doc/user/config-multiple-workers.rst diff --git a/doc/config-network-client.rst b/doc/user/config-network-client.rst similarity index 100% rename from doc/config-network-client.rst rename to doc/user/config-network-client.rst diff --git a/doc/config-network-dns-tweaks.rst b/doc/user/config-network-dns-tweaks.rst similarity index 100% rename from doc/config-network-dns-tweaks.rst rename to doc/user/config-network-dns-tweaks.rst diff --git a/doc/config-network-server-tls.rst b/doc/user/config-network-server-tls.rst similarity index 100% rename from doc/config-network-server-tls.rst rename to doc/user/config-network-server-tls.rst diff --git a/doc/config-network-server.rst b/doc/user/config-network-server.rst similarity index 96% rename from doc/config-network-server.rst rename to doc/user/config-network-server.rst index 7e98dbca3..e6db04fef 100644 --- a/doc/config-network-server.rst +++ b/doc/user/config-network-server.rst @@ -23,10 +23,10 @@ address + port combination. :header: "Protocol/service", :option:`kind ` "DNS (unencrypted UDP+TCP, :rfc:`1034`)","``dns``" - "DNS (unencrypted UDP, :ref:`using XDP Linux API `)","``xdp``" + "DNS (unencrypted UDP, `using XDP Linux API <./dev/daemon-bindings-net_server.html#dns-over-xdp>`_)","``xdp``" ":ref:`dns-over-tls`","``dot``" ":ref:`dns-over-https`","``doh2``" - ":ref:`mod-http-doh`","``doh-legacy``" + "`Legacy DNS-over-HTTPS (DoH) <./dev/modules-http.html#mod-http-doh>`_","``doh-legacy``" .. note:: diff --git a/doc/config-network.rst b/doc/user/config-network.rst similarity index 98% rename from doc/config-network.rst rename to doc/user/config-network.rst index 11d3588ba..ccdf613ca 100644 --- a/doc/config-network.rst +++ b/doc/user/config-network.rst @@ -15,7 +15,7 @@ This picture illustrates different actors involved DNS resolution process, supported protocols, and clarifies what we call *server configuration* and *client configuration*. -.. image:: server_terminology.svg +.. image:: ../server_terminology.svg *Attribution: Icons by Bernar Novalyi from the Noun Project* diff --git a/doc/config-nsid.rst b/doc/user/config-nsid.rst similarity index 87% rename from doc/config-nsid.rst rename to doc/user/config-nsid.rst index 8e9dedf0f..237eefb86 100644 --- a/doc/config-nsid.rst +++ b/doc/user/config-nsid.rst @@ -9,7 +9,7 @@ Knot Resolver provides server-side support for :rfc:`5001` which allows DNS clients to request resolver to send back its NSID along with the reply to a DNS request. This is useful for debugging larger resolver farms -(e.g. when using :ref:`systemd-multiple-instances`, anycast or load balancers). +(e.g. when using multiple instances of Knot Resolver, anycast or load balancers). NSID value can be configured in the resolver's configuration file: diff --git a/doc/config-overview.rst b/doc/user/config-overview.rst similarity index 100% rename from doc/config-overview.rst rename to doc/user/config-overview.rst diff --git a/doc/config-performance.rst b/doc/user/config-performance.rst similarity index 100% rename from doc/config-performance.rst rename to doc/user/config-performance.rst diff --git a/doc/config-policy-new.rst b/doc/user/config-policy-new.rst similarity index 100% rename from doc/config-policy-new.rst rename to doc/user/config-policy-new.rst diff --git a/doc/config-priming.rst b/doc/user/config-priming.rst similarity index 100% rename from doc/config-priming.rst rename to doc/user/config-priming.rst diff --git a/doc/config-rebinding.rst b/doc/user/config-rebinding.rst similarity index 100% rename from doc/config-rebinding.rst rename to doc/user/config-rebinding.rst diff --git a/doc/config-refuse-no-rd.rst b/doc/user/config-refuse-no-rd.rst similarity index 100% rename from doc/config-refuse-no-rd.rst rename to doc/user/config-refuse-no-rd.rst diff --git a/doc/config-renumber.rst b/doc/user/config-renumber.rst similarity index 100% rename from doc/config-renumber.rst rename to doc/user/config-renumber.rst diff --git a/doc/config-reordering.rst b/doc/user/config-reordering.rst similarity index 100% rename from doc/config-reordering.rst rename to doc/user/config-reordering.rst diff --git a/doc/config-rfc7706.rst b/doc/user/config-rfc7706.rst similarity index 100% rename from doc/config-rfc7706.rst rename to doc/user/config-rfc7706.rst diff --git a/doc/config-serve-stale.rst b/doc/user/config-serve-stale.rst similarity index 100% rename from doc/config-serve-stale.rst rename to doc/user/config-serve-stale.rst diff --git a/doc/config-ta-sentinel.rst b/doc/user/config-ta-sentinel.rst similarity index 100% rename from doc/config-ta-sentinel.rst rename to doc/user/config-ta-sentinel.rst diff --git a/doc/config-ta-signal-query.rst b/doc/user/config-ta-signal-query.rst similarity index 100% rename from doc/config-ta-signal-query.rst rename to doc/user/config-ta-signal-query.rst diff --git a/doc/config-time-jump-detection.rst b/doc/user/config-time-jump-detection.rst similarity index 100% rename from doc/config-time-jump-detection.rst rename to doc/user/config-time-jump-detection.rst diff --git a/doc/config-time-skew-detection.rst b/doc/user/config-time-skew-detection.rst similarity index 100% rename from doc/config-time-skew-detection.rst rename to doc/user/config-time-skew-detection.rst diff --git a/doc/config-views.rst b/doc/user/config-views.rst similarity index 97% rename from doc/config-views.rst rename to doc/user/config-views.rst index 9781d612b..ed73de02f 100644 --- a/doc/config-views.rst +++ b/doc/user/config-views.rst @@ -48,7 +48,7 @@ Conditions This is the only mandatory part of each rule. You may use ``[ 0.0.0.0/0, "::/0" ]`` to match all external requests. - .. option:: dst-subnet + .. option:: dst-subnet: Destination subnet, i.e. restricting the IP address that accepted the query. @@ -58,7 +58,7 @@ Conditions the destination address for UDP queries will be just that instead of the real address. - .. option:: protocols + .. option:: protocols: List of protocols for the query; subset of: ``udp53``, ``tcp53``, ``dot``, ``doh``, ``doq``. diff --git a/doc/deployment-advanced-no-manager.rst b/doc/user/deployment-advanced-no-manager.rst similarity index 100% rename from doc/deployment-advanced-no-manager.rst rename to doc/user/deployment-advanced-no-manager.rst diff --git a/doc/deployment-no-systemd-privileges.rst b/doc/user/deployment-advanced-no-systemd-privileges.rst similarity index 100% rename from doc/deployment-no-systemd-privileges.rst rename to doc/user/deployment-advanced-no-systemd-privileges.rst diff --git a/doc/deployment-no-systemd-processes.rst b/doc/user/deployment-advanced-no-systemd-processes.rst similarity index 85% rename from doc/deployment-no-systemd-processes.rst rename to doc/user/deployment-advanced-no-systemd-processes.rst index 362e85460..4800ba964 100644 --- a/doc/deployment-no-systemd-processes.rst +++ b/doc/user/deployment-advanced-no-systemd-processes.rst @@ -11,7 +11,7 @@ There following should be taken into consideration when running without systemd: processes. * Maintenance daemon(s) have to be executed separately. * If a process crashes, it might be useful to restart it. -* Using some mechanism similar to :ref:`mod-watchdog` might be desirable to +* Using some mechanism similar to `watchdog <./dev/modules-watchdog.html#mod-watchdog>`_ might be desirable to recover in case a process becomes unresponsive. Please note, systemd isn't the only process manager and other solutions exist, @@ -22,6 +22,6 @@ It is also possible to use kresd without any process management at all, which may be suitable for some purposes (such as low-traffic local / home network resolver, testing, development or debugging). -.. include:: ../utils/cache_gc/README.rst +.. include:: ../../utils/cache_gc/README.rst .. _`supervisord`: http://supervisord.org/ diff --git a/doc/deployment-no-systemd.rst b/doc/user/deployment-advanced-no-systemd.rst similarity index 94% rename from doc/deployment-no-systemd.rst rename to doc/user/deployment-advanced-no-systemd.rst index 68b3464ab..c1a585eb5 100644 --- a/doc/deployment-no-systemd.rst +++ b/doc/user/deployment-advanced-no-systemd.rst @@ -33,7 +33,7 @@ mind when configuring and running kresd without systemd integration. .. toctree:: :maxdepth: 2 - deployment-no-systemd-processes - deployment-no-systemd-privileges + deployment-advanced-no-systemd-processes + deployment-advanced-no-systemd-privileges .. _`#529`: https://gitlab.nic.cz/knot/knot-resolver/issues/529 diff --git a/doc/deployment-advanced.rst b/doc/user/deployment-advanced.rst similarity index 74% rename from doc/deployment-advanced.rst rename to doc/user/deployment-advanced.rst index 8b39b23fa..5739b9f61 100644 --- a/doc/deployment-advanced.rst +++ b/doc/user/deployment-advanced.rst @@ -6,4 +6,4 @@ Advanced :maxdepth: 2 deployment-advanced-no-manager - deployment-no-systemd \ No newline at end of file + deployment-advanced-no-systemd \ No newline at end of file diff --git a/doc/deployment-docker.rst b/doc/user/deployment-docker.rst similarity index 100% rename from doc/deployment-docker.rst rename to doc/user/deployment-docker.rst diff --git a/doc/deployment-manual.rst b/doc/user/deployment-manual.rst similarity index 100% rename from doc/deployment-manual.rst rename to doc/user/deployment-manual.rst diff --git a/doc/deployment-systemd.rst b/doc/user/deployment-systemd.rst similarity index 90% rename from doc/deployment-systemd.rst rename to doc/user/deployment-systemd.rst index b384adf1f..fc52e98ac 100644 --- a/doc/deployment-systemd.rst +++ b/doc/user/deployment-systemd.rst @@ -12,7 +12,7 @@ In the default installation, Knot Resolver contains systemd integration and star If you don't have systemd service file for Knot Resolver already installed in your system, you can create one manually with the folling content: -.. literalinclude:: ../systemd/knot-resolver.service.in +.. literalinclude:: ../../systemd/knot-resolver.service.in :language: bash .. note:: diff --git a/doc/deployment-warning.rst b/doc/user/deployment-warning.rst similarity index 100% rename from doc/deployment-warning.rst rename to doc/user/deployment-warning.rst diff --git a/doc/user/developer.rst b/doc/user/developer.rst new file mode 100644 index 000000000..2d8c1faf3 --- /dev/null +++ b/doc/user/developer.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-3.0-or-later + +.. _developer: + +*********************** +Developer documentation +*********************** + +For simplicity of this user documentation, `the developer documentation <./dev/index.html>`_ is separated. diff --git a/doc/gettingstarted-config.rst b/doc/user/gettingstarted-config.rst similarity index 99% rename from doc/gettingstarted-config.rst rename to doc/user/gettingstarted-config.rst index 5e993d44b..bc3aab5a8 100644 --- a/doc/gettingstarted-config.rst +++ b/doc/user/gettingstarted-config.rst @@ -265,7 +265,7 @@ Knot Resolver's cache contains data its clients queried for. If you are concerned about attackers who are able to get access to your computer system in power-off state, and your storage device is not secured by encryption, you can move the cache to tmpfs_. -See :ref:`cache_persistence`. +See :ref:`config-cache-persistence`. .. .. raw:: html diff --git a/doc/gettingstarted-install.rst b/doc/user/gettingstarted-install.rst similarity index 93% rename from doc/gettingstarted-install.rst rename to doc/user/gettingstarted-install.rst index 7efd4a5f7..e7e922dc5 100644 --- a/doc/gettingstarted-install.rst +++ b/doc/user/gettingstarted-install.rst @@ -42,6 +42,4 @@ Please, follow the instructions for your packaging system: Hub page: https://hub.docker.com/r/cznic/knot-resolver - - -If for some reason you need to install Knot Resolver **from source**, check out :ref:`building from sources ` documentation for developers. +If for some reason you need to install Knot Resolver **from sources**, check out `building from sources <./dev/build.html>`_ in developer documentation. diff --git a/doc/gettingstarted-startup.rst b/doc/user/gettingstarted-startup.rst similarity index 100% rename from doc/gettingstarted-startup.rst rename to doc/user/gettingstarted-startup.rst diff --git a/doc/index.rst b/doc/user/index.rst similarity index 89% rename from doc/index.rst rename to doc/user/index.rst index 0308bed14..e2706f8c8 100644 --- a/doc/index.rst +++ b/doc/user/index.rst @@ -56,25 +56,16 @@ If you are a completely new user or new to version 6, please start with chapters :name: operators-chapter :maxdepth: 1 - upgrading-to-6 upgrading + upgrading-to-6 NEWS - .. toctree:: :caption: For developers - :name: developers-chapter - :maxdepth: 2 - - manager-dev - internal-lua-config - architecture - build - lib - modules_api - worker_api - modules-http-custom-services + :name: developer-chapter + :maxdepth: 1 + developer Indices and tables ================== diff --git a/doc/manager-api.rst b/doc/user/manager-api.rst similarity index 99% rename from doc/manager-api.rst rename to doc/user/manager-api.rst index 80dcc4afa..cc297cc47 100644 --- a/doc/manager-api.rst +++ b/doc/user/manager-api.rst @@ -110,4 +110,3 @@ The different HTTP methods perform different modifications of the configuration: To prevent race conditions when changing configuration from multiple clients simultaneously, every response from the Manager has an ``ETag`` header set. Requests then accept ``If-Match`` and ``If-None-Match`` headers with the latest ``ETag`` value and the corresponding request processing fails with HTTP error code 412 (precondition failed). - diff --git a/doc/manager-client.rst b/doc/user/manager-client.rst similarity index 100% rename from doc/manager-client.rst rename to doc/user/manager-client.rst diff --git a/doc/upgrading-to-6.rst b/doc/user/upgrading-to-6.rst similarity index 92% rename from doc/upgrading-to-6.rst rename to doc/user/upgrading-to-6.rst index 1028d5b43..9a9db0459 100644 --- a/doc/upgrading-to-6.rst +++ b/doc/user/upgrading-to-6.rst @@ -49,9 +49,13 @@ The resolver then listens on ``localhost`` with the standard unencrypted DNS pro To write your own configuration, you can start with the :ref:`getting started chapter for configuration `. -If you need to rewrite the old Lua configuration to the new declarative one, -it's a good idea to find the option you want to convert in the :ref:`internal Lua configuration `, -and the equivalent option will very likely be in the :ref:`new declarative configuration ` documentation in a similar place. +Conversion to |yaml| +-------------------- + +Lua configuration is considered internal as of version 6 and can be found in the `developer documentation`_, which is separate from the user documentation. + +To switch from your old Lua configuration, it is a good idea to open this `developer documentation`_ and find the Lua option you want to convert. +Also open the :ref:`new declarative configuration ` documentation. The equivalent |yaml| option will very likely in a similar place. The documentation structure is basically the same. Otherwise, you will have to search for the option in the documentation separately. @@ -99,3 +103,5 @@ validate new config ``kresctl validate path/to/new/confi look at the Lua config ``kresctl convert path/to/new/config.yaml`` ``cat /path/to/config.conf`` gather metrics point Prometheus etc. at the single HTTP API collect metrics manually from all individual processes ========================================== =========================================================================================== ================================================================== + +.. _`developer documentation`: ./dev/index.html diff --git a/doc/user/upgrading.rst b/doc/user/upgrading.rst new file mode 100644 index 000000000..05374f652 --- /dev/null +++ b/doc/user/upgrading.rst @@ -0,0 +1,21 @@ +.. SPDX-License-Identifier: GPL-3.0-or-later + +.. _upgrading: + +********* +Upgrading +********* + +This section summarizes steps required when upgrading to newer Knot Resolver versions. +We advise users to also read :ref:`release_notes` for respective versions. + +5.x to 6.x +========== + +See the detailed guide for :ref:`upgrading to version 6.x `. + +Older versions +============== + +Information for upgrading older versions of the resolver can be found in the older documentation +hosted on `knot-resolver.readthedocs.io/ `_. diff --git a/scripts/make-doc.sh b/scripts/make-doc.sh index 6cefd6c51..1723ada76 100755 --- a/scripts/make-doc.sh +++ b/scripts/make-doc.sh @@ -11,10 +11,15 @@ 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 popd -pushd doc +# generating the user documentation +SPHINX=$(type -P sphinx-build-3 sphinx-build | head -n1) +rm -rf doc/html +"$SPHINX" "$@" -b html -d doc/user/.doctrees doc/user doc/html + +pushd doc/dev doxygen popd -SPHINX=$(type -P sphinx-build-3 sphinx-build | head -n1) -rm -rf doc/html -"$SPHINX" "$@" -b html -d doc/.doctrees doc doc/html +# generating the developer documentation +rm -rf doc/html/dev +"$SPHINX" "$@" -b html -d doc/dev/.doctrees doc/dev doc/html/dev