--- /dev/null
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _dnssec-config:
+
+*************************
+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
+
+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
--- /dev/null
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+*********************
+Experimental features
+*********************
+
+Following functionality and APIs are in continuous development.
+Features in this section may changed, replaced or dropped in any release.
+
+.. toctree::
+ :maxdepth: 1
+
+ daemon-scripting
+ modules-experimental_dot_auth
--- /dev/null
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+********************************
+Logging, monitoring, diagnostics
+********************************
+
+To read service logs use commands usual for your distribution.
+E.g. on distributions using systemd-journald use command ``journalctl -u kresd@* -f``.
+
+Knot Resolver supports 6 logging levels - ``crit``, ``err``, ``warning``,
+``notice``, ``info``, ``debug``. All levels with the same meaning as is defined
+in ``syslog.h``. It is possible change logging level using
+:func:`log_level` function.
+
+.. code-block:: lua
+
+ log_level('debug') -- too verbose for normal usage
+
+Logging level ``notice`` is set after start by default,
+so logs from Knot Resolver should contain only couple lines a day.
+For debugging purposes it is possible to use the very verbose ``debug`` level,
+but that is generally not usable unless restricted in some way (see below).
+
+In addition to levels, logging is also divided into the
+:ref:`groups <config_log_groups>`. All groups
+are logged by default, but you can enable ``debug`` level for selected groups using
+:func:`log_groups` function. Other groups are logged to the log level
+set by :func:`log_level`.
+
+It is also possible to enable ``debug`` logging level for particular requests,
+with :ref:`policies <mod-policy-logging>` or as :ref:`an HTTP service <mod-http-trace>`.
+
+Less verbose logging for DNSSEC validation errors can be enabled by using :ref:`mod-bogus_log` module.
+
+.. py:function:: log_level([level])
+
+ :param: string ``'crit'``, ``'err'``, ``'warning'``, ``'notice'``,
+ ``'info'`` or ``'debug'``
+ :return: string Current logging level.
+
+ Pass a string to set the global logging level.
+
+ .. py:function:: verbose([true | false])
+
+ .. deprecated:: 5.4.0
+ Use :func:`log_level` instead.
+
+ :param: ``true`` enable ``debug`` level, ``false`` switch to default level (``notice``).
+ :return: boolean ``true`` when ``debug`` level is enabled.
+
+ Toggle between ``debug`` and ``notice`` log level. Use only for debugging purposes.
+ On busy systems verbose logging can produce several MB of logs per
+ second and will slow down operation.
+
+.. py:function:: log_target(target)
+
+ :param: string ``'syslog'``, ``'stderr'``, ``'stdout'``
+ :return: string Current logging target.
+
+ Knot Resolver logs to standard error stream by default,
+ but typical systemd units change that to ``'syslog'``.
+ That setting logs directly through systemd's facilities
+ (if available) to preserve more meta-data.
+
+.. py:function:: log_groups([table])
+
+ :param: table of string(s) representing :ref:`log groups <config_log_groups>`
+ :return: table of string with currently set log groups
+
+ Use to turn-on debug logging for the selected groups regardless of the global
+ log level. Calling with no argument lists the currently active log groups. To
+ remove all log groups, call the function with an empty table.
+
+ .. code-block:: lua
+
+ log_groups({'io', 'tls'} -- turn on debug logging for io and tls groups
+ log_groups() -- list active log groups
+ log_groups({}) -- remove all log groups
+
+Various statistics for monitoring purposes are available in :ref:`mod-stats` module, including export to central systems like Graphite, Metronome, InfluxDB, or Prometheus format.
+
+Resolver :ref:`mod-watchdog` is tool to detect and recover from potential bugs that cause the resolver to stop responding properly to queries.
+
+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`.
+
+.. toctree::
+ :maxdepth: 1
+
+ modules-bogus_log
+ modules-stats
+ daemon-bindings-worker
+ modules-nsid
+ modules-http-trace
+ modules-watchdog
+ modules-dnstap
+ modules-ta_sentinel
+ modules-ta_signal_query
+ modules-detect_time_skew
+ modules-detect_time_jump
+ config-debugging
+ config-logging-header
--- /dev/null
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _config-lua-network:
+
+************************
+Networking and protocols
+************************
+
+This section describes configuration of network interfaces
+and protocols. Please keep in mind that DNS resolvers act
+as *DNS server* and *DNS client* at the same time,
+and that these roles require different configuration.
+
+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
+
+*Attribution: Icons by Bernar Novalyi from the Noun Project*
+
+For *resolver's clients* the resolver itself acts as a DNS server.
+
+After receiving a query the resolver will attempt to find
+answer in its cache. If the data requested by resolver's
+client is not available in resolver's cache (so-called *cache-miss*)
+the resolver will attempt to obtain the data from servers *upstream*
+(closer to the source of information), so at this point the resolver
+itself acts like a DNS client and will send DNS query to other servers.
+
+By default the Knot Resolver works in recursive mode, i.e.
+the resolver will contact authoritative servers on the Internet.
+Optionally it can be configured in forwarding mode,
+where cache-miss queries are *forwarded to another DNS resolver*
+for processing.
+
+Server (communication with clients)
+===================================
+
+.. toctree::
+ :maxdepth: 2
+
+ daemon-bindings-net_server
+ daemon-bindings-net_tlssrv
+ modules-http
+
+Client (retrieving answers from servers)
+========================================
+
+Following chapters describe basic configuration of how resolver retrieves data from other *(upstream)* servers. Data processing is also affected by configured policies, see chapter :ref:`policies` for more advanced usage.
+
+.. toctree::
+ :maxdepth: 2
+
+ daemon-bindings-net_client
+ config-network-forwarding
+
+DNS protocol tweaks
+===================
+
+.. toctree::
+ :maxdepth: 2
+
+ daemon-bindings-net_dns_tweaks
-.. _config-syntax:
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _config-lua-syntax:
Syntax
======
--- /dev/null
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _config-lua-performance:
+
+**************************
+Performance and resiliency
+**************************
+
+For DNS resolvers, the most important parameter from performance perspective
+is cache hit rate, i.e. percentage of queries answered from resolver's cache.
+Generally the higher cache hit rate the better.
+
+Performance tunning should start with cache :ref:`cache_sizing`
+and :ref:`cache_persistence`.
+
+It is also recommended to run :ref:`systemd-multiple-instances` (even on a
+single machine!) because it allows to utilize multiple CPU threads and
+increases overall resiliency.
+
+Other features described in this section can be used for fine-tunning
+performance and resiliency of the resolver but generally have much smaller
+impact than cache settings and number of instances.
+
+.. toctree::
+ :maxdepth: 1
+
+ daemon-bindings-cache
+ systemd-multiinst
+ modules-predict
+ modules-prefill
+ modules-serve_stale
+ modules-rfc7706
+ modules-priming
+ modules-edns_keepalive
+ daemon-bindings-net_xdpsrv
--- /dev/null
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _policies:
+
+*****************************************
+Policy, access control, data manipulation
+*****************************************
+
+Features in this section allow to configure what clients can get access to what
+DNS data, i.e. DNS data filtering and manipulation.
+
+:ref:`mod-policy` specify global policies applicable to all requests,
+e.g. for blocking access to particular domain. :ref:`mod-view` allow
+to specify per-client policies, e.g. block or unblock access
+to a domain only for subset of clients.
+
+It is also possible to modify data returned to clients, either by providing
+:ref:`mod-hints` (answers with statically configured IP addresses),
+:ref:`mod-dns64` translation, or :ref:`mod-renumber`.
+
+Additional modules offer protection against various DNS-based attacks,
+see :ref:`mod-rebinding` and :ref:`mod-refuse_nord`.
+
+At the very end, module :ref:`mod-daf` provides HTTP API for run-time policy
+modification, and generally just offers different interface for previously
+mentioned features.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ modules-policy
+ modules-view
+ modules-hints
+ modules-dns64
+ modules-renumber
+ config-answer-reordering
+ modules-rebinding
+ modules-refuse_nord
+ modules-daf
+
+.. SPDX-License-Identifier: GPL-3.0-or-later
-Advanced configuration (Lua)
-============================
+.. _config-lua:
-Knot Resolver can be configured declaratively by using YAML files or YAML/JSON HTTP API. However, there is another option. The actual worker processes (the ``kresd`` executable) speaks a different configuration language, it internally uses the Lua runtime and the respective programming language.
+*************
+Lua Scripting
+*************
-Essentially, the declarative configuration is only used for validation and as an external interface. After validation, a Lua configuration is generated and passed into individual ``kresd`` instances. You can see the generated configuration files within the Resolver's working directory or you can manually run the conversion of declarative configuration with the ``kresctl convert`` command.
+Knot Resolver can be configured declaratively by using YAML configuration file.
+The actual worker processes (the ``kresd`` executable) speaks a different configuration language, it internally uses the Lua runtime.
+
+Essentially, the declarative configuration is only used for validation and as an external interface.
+After validation, a Lua configuration is generated and passed into individual ``kresd`` workers.
+
+You can see the generated configuration files within the resolver's working directory or you can manualy run the conversion of declarative configuration with the :ref:`kresctl convert <manager-client>` command.
+In the declarative configuration there is a ``lua`` section where you can insert your own Lua configuration scripts.
.. warning::
- While there are no plans of ever removing the Lua configuration, we do not guarantee absence of backwards incompatible changes. Starting with Knot Resolver version 6 and later, we consider the Lua interface internal and a subject to change. While we don't have any breaking changes planned for the foreseeable future, they might come.
- **Therefore, use this only when you don't have any other option. And please let us know about it and we might try to accomodate your usecase in the declarative configuration.**
+ While there are no plans of ever removing the Lua configuration, we do not guarantee absence of backwards incompatible changes.
+ Starting with Knot Resolver version 6 and later, we consider the Lua interface internal and a subject to change.
+ While we don't have any breaking changes planned for the foreseeable future, they might come.
+
+ **Therefore, use this only when you don't have any other option.
+ And please let us know about it and we might try to accomodate your usecase in the declarative configuration.**
+
+.. option:: lua/script-only: true|false
+
+ :default: false
+
+ Ignore declarative configuration for ``kresd`` workers and use only Lua script or script file configured in this section.
+
+.. option:: lua/script: <script string>
+
+ Custom Lua configuration script.
+
+ .. code-block:: yaml
+
+ lua:
+ script: |
+ -- Network interface configuration
+ net.listen('127.0.0.1', 53, { kind = 'dns' })
+ net.listen('::1', 53, { kind = 'dns', freebind = true })
+
+ -- Load useful modules
+ modules = {
+ 'hints > iterate', -- Allow loading /etc/hosts or custom root hints
+ 'stats', -- Track internal statistics
+ 'predict', -- Prefetch expiring/frequent records
+ }
+
+ -- Cache size
+ cache.size = 100 * MB
+
+.. option:: lua/script-file: <path>
+
+ Path to the file that contains Lua configuration script.
+
+.. note::
+
+ The script is applied after the declarative configuration, so it can change the configuration defined in it.
.. toctree::
:maxdepth: 2
-
+
config-lua-overview
- config-network
- config-performance
- config-policy
- config-logging-monitoring
- config-dnssec
- config-experimental
\ No newline at end of file
+ config-lua-network
+ config-lua-performance
+ config-lua-policy
+ config-lua-logging-monitoring
+ config-lua-dnssec
+ config-lua-experimental
config-overview
usecase-network-interfaces
config-policy-new
+ config-dnssec
config-lua
.. toctree::
projects / thirdparty / knot-resolver.git / commitdiff
