.. _`JSON-encoded`: http://json.org/example
-.. _`Learn Lua in 15 minutes`: http://tylerneylon.com/a/learn-lua/
.. _`PowerDNS Recursor`: https://doc.powerdns.com/md/recursor/scripting/
.. _libuv: https://github.com/libuv/libuv
.. _Lua: https://www.lua.org/about.html
Cache
------
+=====
-Cache in Knot Resolver is stored on disk and also shared between `Multiple instances`_
-so resolver doesn't lose the cached data on restart or crash.
+Cache in Knot Resolver is stored on disk and also shared between
+:ref:`systemd-multiple-instances` so resolver doesn't lose the cached data on
+restart or crash.
To improve performance even further the resolver implements so-called aggressive caching
for DNSSEC-validated data (:rfc:`8198`), which improves performance and also protects
.. _`cache_sizing`:
Sizing
-^^^^^^
+------
For personal and small office use-cases cache size around 100 MB is more than enough.
.. _`cache_persistence`:
Persistence
-^^^^^^^^^^^
+-----------
.. tip:: Using tmpfs for cache improves performance and reduces disk I/O.
By default the cache is saved on a persistent storage device
.. _tmpfs: https://en.wikipedia.org/wiki/Tmpfs
Configuration reference
-^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------
.. function:: cache.open(max_size[, config_uri])
Modules
--------
+=======
+
Knot Resolver functionality consists of separate modules, which allow you
to mix-and-match features you need without slowing down operation
by features you do not use.
--- /dev/null
+Client
+======
+
+Following settings affect client part of the resolver, i.e. communication between the resolver itself and other DNS servers.
+
+.. envvar:: net.ipv4 = true|false
+
+ :return: boolean (default: true)
+
+ Enable/disable using IPv4 for contacting upstream nameservers.
+
+.. function:: net.outgoing_v4([string address])
+
+ Get/set the IPv4 address used to perform queries.
+ The default is ``nil``, which lets the OS choose any address.
+
+.. envvar:: net.ipv6 = true|false
+
+ :return: boolean (default: true)
+
+ Enable/disable using IPv6 for contacting upstream nameservers.
+
+.. function:: net.outgoing_v6([string address])
+
+ Get/set the IPv6 address used to perform queries.
+ The default is ``nil``, which lets the OS choose any address.
+
--- /dev/null
+DNS protocol tweaks
+===================
+
+Following settings change low-level details of DNS protocol implementation.
+Default values should not be changed except for very special cases.
+
+.. function:: net.bufsize([udp_bufsize])
+
+ Get/set maximum EDNS payload size advertised in DNS packets. Default is 4096 bytes and the default will be lowered to value around 1220 bytes in future, once `DNS Flag Day 2020 <https://dnsflagday.net/>`_ becomes effective.
+
+ Minimal value allowed by standard :rfc:`6891` is 512 bytes, which is equal to DNS packet size without Extension Mechanisms for DNS. Value 1220 bytes is minimum size required in DNSSEC standard :rfc:`4035`.
+
+ Example output:
+
+ .. code-block:: lua
+
+ > net.bufsize(4096)
+ nil
+ > net.bufsize()
+ 4096
+
+.. include:: ../modules/workarounds/README.rst
.. _network-configuration:
Server addresses
------------------
+================
Modern Linux distributions use so-called *Systemd socket activation*, which
effectively means that IP addresses and ports to listen on are configured
addresses if the network address ranges overlap,
and clients would probably refuse such a response.
-**Network configuration using systemd**
+Network configuration using systemd
+-----------------------------------
If you're using our packages with systemd with sockets support (not supported
on CentOS 7), network interfaces are configured using systemd drop-in files.
Also, don't forget to :ref:`load http module in configuration <mod-http-example>`
file, otherwise the socket won't work.
-**Legacy network configuration using configuration file**
+Legacy network configuration using configuration file
+-----------------------------------------------------
If you don't use systemd with sockets to run kresd, addresses and ports to listen
on are configured in the config file.
Close all endpoints listening on the specified address, optionally restricted by port as well.
-**Additional network configuration options**
+Additional network configuration options
+----------------------------------------
Following commands are useful in special situations and can be usef with and without systemd socket activation:
.. warning:: Please note that too large limit may have negative impact on performance and can lead to increased number of SERVFAIL answers.
-Client
-------
-Following settings affect client part of the resolver, i.e. communication between the resolver itself and other DNS servers.
+.. _`dnsproxy module`: https://www.knot-dns.cz/docs/2.7/html/modules.html#dnsproxy-tiny-dns-proxy
-.. envvar:: net.ipv4 = true|false
-
- :return: boolean (default: true)
-
- Enable/disable using IPv4 for contacting upstream nameservers.
-
-.. function:: net.outgoing_v4([string address])
-
- Get/set the IPv4 address used to perform queries.
- The default is ``nil``, which lets the OS choose any address.
-
-.. envvar:: net.ipv6 = true|false
-
- :return: boolean (default: true)
-
- Enable/disable using IPv6 for contacting upstream nameservers.
-
-.. function:: net.outgoing_v6([string address])
-
- Get/set the IPv6 address used to perform queries.
- The default is ``nil``, which lets the OS choose any address.
-
-DNS protocol
-------------
-Following settings change low-level details of DNS protocol implementation.
-Default values should not be changed except for very special cases.
-
-.. function:: net.bufsize([udp_bufsize])
-
- Get/set maximum EDNS payload size advertised in DNS packets. Default is 4096 bytes and the default will be lowered to value around 1220 bytes in future, once `DNS Flag Day 2020 <https://dnsflagday.net/>`_ becomes effective.
-
- Minimal value allowed by standard :rfc:`6891` is 512 bytes, which is equal to DNS packet size without Extension Mechanisms for DNS. Value 1220 bytes is minimum size required in DNSSEC standard :rfc:`4035`.
-
- Example output:
-
- .. code-block:: lua
-
- > net.bufsize(4096)
- nil
- > net.bufsize()
- 4096
-
-.. include:: ../modules/workarounds/README.rst
.. _tls-server-config:
DNS-over-TLS server (DoT)
--------------------------
+=========================
+
DNS-over-TLS server (:rfc:`7858`) is enabled by default on loopback interface port 853.
Information how to configure listening on specific IP addresses is in previous sections
:ref:`network-configuration`.
-.. _dnssec-config:
+Trust anchors
+=============
-DNSSEC, data verification
-=========================
-
-Since version 4.0, **DNSSEC validation is enabled by default**.
-This is secure default and should not be changed unless absolutely necessary.
-
-**Options in this section are intended only for expert users and normally
-should not be needed.**
+.. warning:: Options in this section are intended only for expert users and
+ normally should not be needed.
If you really need to turn DNSSEC off and are okay with lowering security of your
system by doing so, add the following snippet to your configuration file.
Return string with summary of configured DNSSEC trust anchors, including negative TAs.
-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
+.. _lua-http: https://luarocks.org/modules/daurnimator/http
---------------
Control socket acts like "an interactive configuration file" so all actions available in configuration file can be executed interactively using the control socket. One possible use-case is reconfiguring Resolver instances from another program, e.g. a maintenance script.
-.. note::
+.. note:: Each instance of Knot Resolver exposes its own control socket. Take
+ that into account when scripting deployments with
+ :ref:`systemd-multiple-instances`.
- Each instance of Knot Resolver exposes its own control socket. Take that into account when scripting deployments with `Multiple instances`_.
-
-When Knot Resolver is started using Systemd (see section :ref:`startup`) it creates a control socket in path ``/run/knot-resolver/control@$INSTANCENAME``. Connection to the socket can be made from command line using e.g. ``netcat`` or ``socat``:
+When Knot Resolver is started using Systemd (see section :ref:`quickstart-startup`) it creates a control socket in path ``/run/knot-resolver/control@$INSTANCENAME``. Connection to the socket can be made from command line using e.g. ``netcat`` or ``socat``:
.. code-block:: bash
--- /dev/null
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 23.0.6, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
+<svg version="1.1" id="Vrstva_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+ viewBox="0 0 600 161" style="enable-background:new 0 0 600 161;" xml:space="preserve" width="200" height="54">
+<style type="text/css">
+ .st0{fill:#FFFFFF;}
+</style>
+<path class="st0" d="M158.6,80.6c0,24.2-10.7,45.8-27.7,60.4c1-4.9,1.5-9.9,1.5-15.1c0-15.8-4.7-30.5-12.7-42.9
+ c-3.2,4.4-6.8,8.5-10.7,12.1c5.1,9.1,8,19.6,8,30.8c0,4.5-0.5,8.9-1.4,13.2c-0.1,0.5-0.2,0.9-0.3,1.4c-0.1,0.4-0.2,0.9-0.3,1.4
+ c-0.5-0.1-0.9-0.2-1.4-0.4c-0.4-0.1-0.9-0.3-1.3-0.4c-14.6-4.8-26.9-14.7-34.8-27.6c-0.2-0.4-0.5-0.8-0.7-1.3
+ c-0.3-0.4-0.5-0.8-0.7-1.2c-2.5-4.5-4.4-9.4-5.7-14.4c-0.1-0.5-0.2-0.9-0.3-1.4c-0.1-0.4-0.2-0.9-0.3-1.4c-0.9-4.3-1.4-8.7-1.4-13.2
+ c0-4.5,0.5-8.9,1.4-13.2c-4.9-1.4-10-2.1-15.3-2.2c-1,5-1.5,10.1-1.5,15.4c0,5.3,0.5,10.4,1.5,15.4c0.1,0.5,0.2,0.9,0.3,1.4
+ c0.1,0.5,0.2,1,0.3,1.4c1.2,5.3,3,10.3,5.3,15.2c0.2,0.4,0.4,0.9,0.6,1.3c0.2,0.5,0.4,0.9,0.7,1.4c9.3,18.1,25.4,32.1,44.9,38.8
+ c-8.6,3.2-17.9,4.9-27.6,4.9c-39.6,0-72.5-28.8-78.7-66.7c0.3,0.3,0.7,0.6,1.1,0.9c13.9,12.2,32.2,19.7,52.1,19.7
+ c1.3,0,2.6,0,3.9-0.1c-2.2-4.9-4-10-5.2-15.4c-15.8-0.3-30.3-6.4-41.2-16.3c-0.4-0.3-0.7-0.6-1-1c-0.3-0.3-0.7-0.7-1-1
+ c0.3-0.3,0.7-0.7,1-1c0.3-0.3,0.7-0.7,1-1c11-9.9,25.4-16,41.2-16.3c0.4,0,0.8,0,1.2,0h0.2c0.5,0,1,0,1.5,0
+ c5.3,0.1,10.4,0.9,15.4,2.3c0.4,0.1,0.9,0.3,1.3,0.4c0.5,0.1,0.9,0.3,1.3,0.4c8.5,2.8,16.3,7.3,22.8,13.2c3.7-3.6,6.9-7.7,9.6-12.1
+ c-7.7-6.8-16.7-12.1-26.7-15.4c-0.4-0.2-0.9-0.3-1.3-0.4c-0.5-0.2-0.9-0.3-1.4-0.4c-5.1-1.5-10.3-2.6-15.8-3c-0.5-0.1-1-0.1-1.5-0.1
+ c-0.5,0-1-0.1-1.5-0.1c-1.3-0.1-2.6-0.1-3.9-0.1c-19.9,0-38.2,7.4-52.1,19.6c-0.4,0.3-0.7,0.6-1.1,0.9C6.4,29.6,39.2,0.8,78.8,0.8
+ c9.7,0,19,1.7,27.6,4.9c0,0,0,0,0,0C87,12.3,70.9,26.4,61.5,44.5c5.5,0.6,10.8,1.6,15.9,3.2c7.8-12.9,20.2-22.9,34.8-27.6
+ c0.4-0.1,0.9-0.3,1.3-0.4c0.5-0.1,0.9-0.3,1.4-0.4c0.1,0.4,0.2,0.9,0.3,1.4c0.1,0.5,0.2,0.9,0.3,1.4c0.9,4.3,1.4,8.7,1.4,13.2
+ c0,11.1-2.9,21.6-7.9,30.7c-0.2,0.4-0.5,0.8-0.7,1.2c-0.2,0.4-0.5,0.8-0.7,1.2c-2.7,4.4-6,8.5-9.7,12.1c-0.3,0.3-0.7,0.7-1,1
+ c-0.3,0.3-0.7,0.7-1,1C89.3,88.4,81.5,92.9,73,95.7c1.3,5.1,3.3,9.9,5.8,14.4c9.9-3.4,18.9-8.7,26.7-15.5c0.4-0.3,0.7-0.6,1.1-1
+ c0.4-0.3,0.7-0.6,1-1C111.4,89,115,85,118,80.6c0.3-0.4,0.6-0.8,0.9-1.2c0.3-0.4,0.6-0.8,0.8-1.3c8-12.4,12.7-27.1,12.7-42.9
+ c0-5.2-0.5-10.2-1.5-15.1C147.9,34.8,158.6,56.4,158.6,80.6 M244.6,76.6L218,45.2l25.1-26.8h-17.6L204.6,42h-0.2V18.3h-13.8v58.3
+ h13.8V49.8h0.2l21.7,26.8H244.6z M304.6,76.6V18.3h-13.7l0.3,38H291l-23.4-38h-16.1v58.3h13.7l-0.3-38.1h0.2l23.5,38.1H304.6z
+ M376.4,47.2c0-18.7-13.5-30.5-31.8-30.5c-18.2,0-31.7,11.8-31.7,30.5c0,18.4,13.5,31,31.7,31C362.9,78.2,376.4,65.7,376.4,47.2z
+ M361.3,47.2c0,10.5-6.9,18.1-16.7,18.1c-9.8,0-16.6-7.6-16.6-18.1c0-10.2,6.8-17.8,16.6-17.8C354.5,29.4,361.3,37,361.3,47.2z
+ M425.3,30.3v-12h-47v12h16.5v46.3h14.1V30.3H425.3z M238.2,142.8l-15.2-25c7.5-2.3,12.1-7.9,12.1-15.7c0-13.3-11.1-17.6-22.3-17.6
+ h-22.2v58.3h13.8v-23.1h4.8l12.6,23.1H238.2z M221.2,102.4c0,5.9-5.7,7.1-10.2,7.1h-6.7V95.9h7.5C216,95.9,221.2,97,221.2,102.4z
+ M284.8,142.8v-12h-27.1v-12.1h24.2v-11.3h-24.2v-11h25.6V84.5h-39.2v58.3H284.8z M333.7,90.2c-5.1-4.7-12.5-7.2-19.1-7.2
+ c-10.9,0-22.6,5.4-22.6,18.3c0,10.5,7.5,14.3,14.9,16.7c7.7,2.5,12.1,3.9,12.1,8.3c0,4.7-3.8,6.3-8.1,6.3c-4.6,0-9.8-2.6-12.6-6.2
+ l-9.2,9.4c5.1,5.4,13.5,8.4,21.8,8.4c11.5,0,22.3-6,22.3-19.4c0-11.6-10.2-15-18.1-17.5c-5.5-1.7-9-3-9-6.8c0-4.6,4.5-5.8,8.2-5.8
+ c3.6,0,8,2,10.4,5L333.7,90.2z M401.5,113.4c0-18.7-13.5-30.5-31.8-30.5c-18.2,0-31.7,11.8-31.7,30.5c0,18.4,13.5,31,31.7,31
+ C388,144.4,401.5,131.9,401.5,113.4z M386.5,113.4c0,10.5-6.9,18.1-16.7,18.1c-9.8,0-16.6-7.6-16.6-18.1c0-10.2,6.8-17.8,16.6-17.8
+ S386.5,103.2,386.5,113.4z M446.6,142.8v-12.3H424v-46h-14.2v58.3H446.6z M498.2,84.5h-15.6l-13.4,41.3h-0.3l-13.5-41.3h-15.8
+ l22.1,58.3h14.1L498.2,84.5z M543.3,142.8v-12h-27.1v-12.1h24.2v-11.3h-24.2v-11h25.6V84.5h-39.2v58.3H543.3z M600,142.8l-15.2-25
+ c7.5-2.3,12.1-7.9,12.1-15.7c0-13.3-11.1-17.6-22.3-17.6h-22.2v58.3h13.8v-23.1h4.8l12.6,23.1H600z M583,102.4
+ c0,5.9-5.7,7.1-10.2,7.1h-6.7V95.9h7.5C577.8,95.9,583,97,583,102.4z"/>
+</svg>
# General information about the project.
project = u'Knot Resolver'
-copyright = u'2014-2019 CZ.NIC labs'
+copyright = u'2014-2020 CZ.NIC labs'
with open('../meson.build') as f:
for line in f:
match = re.match(r"\s*version\s*:\s*'([^']+)'.*", line)
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
+}
+html_logo = '_static/logo-negativ.svg'
+
# -- Options for LaTeX output --------------------------------------------------
# Grouping the document tree into LaTeX files. List of tuples
--- /dev/null
+Answer reordering
+=================
+Certain clients are "dumb" and always connect to first IP address or name found
+in a DNS answer received from resolver intead of picking randomly.
+As a workaround for such broken clients it is possible to randomize
+order of records in DNS answers sent by resolver:
+
+.. function:: reorder_RR([true | false])
+
+ :param boolean new_value: ``true`` to enable or ``false`` to disable randomization *(optional)*
+ :return: The (new) value of the option
+
+ If set, resolver will vary the order of resource records within RR sets.
+ It is disabled by default.
+
--- /dev/null
+.. _dnssec-config:
+
+*************************
+DNSSEC, data verification
+*************************
+
+Since version 4.0, **DNSSEC validation is enabled by default**.
+This is secure default and should not be changed unless absolutely necessary.
+
+.. include:: ../daemon/lua/trust_anchors.rst
+
+TODO: Some heading?
+===================
+
+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
+*********************
+Experimental Features
+*********************
+
+The functionality and API of experimental features may changed or be dropped
+without any advance notice.
+
+.. toctree::
+ :maxdepth: 1
+
+ modules-experimental_dot_auth
+ daemon-scripting
--- /dev/null
+********************************
+Logging, monitoring, diagnostics
+********************************
+
+Knot Resolver logs to standard outputs, which is then captured by supervisor
+and sent to logging system for further processing.
+To read logs use commands usual for your distribution.
+E.g. on distributions using systemd-journald use command ``journalctl -u kresd@* -f``.
+
+During normal operation only errors and other very important events are logged,
+so by default logs from Knot Resolver should contain only couple lines a day.
+For debugging purposes it is possible to enable very verbose logging using
+:func:`verbose` function.
+
+.. function:: verbose([true | false])
+
+ :param: ``true`` to enable, ``false`` to disable verbose logging.
+ :return: boolean Current state of verbose logging.
+
+ Toggle global verbose logging. Use only for debugging purposes.
+ On busy systems vebose logging can produce several MB of logs per
+ second and will slow down operation.
+
+Less verbose logging for DNSSEC validation errors can be enabled using :ref:`mod-bogus_log` module.
+
+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.
+
+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-nsid
+ modules-stats
+ modules-graphite
+ modules-http-prometheus
+ modules-dnstap
+ modules-watchdog
+ modules-bogus_log
+ modules-http-trace
+ modules-ta_sentinel
+ modules-ta_signal_query
+ modules-detect_time_skew
+ modules-detect_time_jump
--- /dev/null
+************************
+Networking and protocols
+************************
+
+This section describes configuration of network interfaces and protocols.
+
+.. toctree::
+ :maxdepth: 2
+
+ daemon-bindings-net_server
+ daemon-bindings-net_client
+ daemon-bindings-net_tlssrv
+ modules-http
+ modules-http-doh
+ daemon-bindings-net_dns_tweaks
--- /dev/null
+**********************
+Configuration Overview
+**********************
+
+Configuration file is named ``/etc/knot-resolver/kresd.conf`` and is read when
+you execute Knot Resolver using systemd commands described in section
+:ref:`quickstart-startup`. [#]_
+
+.. _config-syntax:
+
+Syntax
+======
+
+The configuration file syntax allows you to specify different kinds of data:
+
+ - ``group.option = 123456``
+ - ``group.option = "string value"``
+ - ``group.command(123456, "string value")``
+ - ``group.command({ key1 = "value1", key2 = 222, key3 = "third value" })``
+ - ``globalcommand(a_parameter_1, a_parameter_2, a_parameter_3, etc)``
+ - ``-- any text after -- sign is ignored till end of line``
+
+Following **configuration file snippet** starts listening for unencrypted and also encrypted DNS queries on IP address 192.0.2.1, and sets cache size.
+
+.. code-block:: lua
+
+ -- this is a comment: listen for unencrypted queries
+ net.listen('192.0.2.1')
+ -- another comment: listen for queries encrypted using TLS on port 853
+ net.listen('192.0.2.1', 853, { kind = 'tls' })
+ -- 10 MB cache is suitable for a very small deployment
+ cache.size = 10 * MB
+
+.. tip::
+ When copy&pasting examples from this manual please pay close
+ attention to brackets and also line ordering - order of lines matters.
+
+ The configuration language is in fact Lua script, so you can use full power
+ of this programming language. See article
+ `Learn Lua in 15 minutes`_ for a syntax overview.
+
+When you modify configuration file on disk restart resolver process to get
+changes into effect. See chapter :ref:`systemd-zero-downtime-restarts` if even short
+outages are not acceptable for your deployment.
+
+.. [#] If you decide to run binary ``/usr/sbin/kresd`` manually (instead of
+ using systemd) do not forget to specify ``-c`` option with path to
+ configuration file, otherwise ``kresd`` will read file named ``config`` from
+ its current working directory.
+
+Documentation Conventions
+=========================
+
+Besides text configuration file, Knot Resolver also supports interactive and dynamic configuration using scripts or external systems, which is described in chapter :ref:`runtime-cfg`. Through this manual we present examples for both usage types - static configuration in a text file (see above) and also the interactive mode.
+
+The **interactive prompt** is denoted by ``>``, so all examples starting with ``>`` character are transcripts of user (or script) interaction with Knot Resolver and resolver's responses. For example:
+
+.. code-block:: lua
+
+ > -- this is a comment entered into interactive prompt
+ > -- comments have no effect here
+ > -- the next line shows a command entered interactivelly and its output
+ > verbose()
+ false
+ > -- the previous line without > character is output from verbose() command
+
+Following example demontrates how to interactivelly list all currently loaded modules, and includes multi-line output:
+
+.. code-block:: lua
+
+ > modules.list()
+ [1] => iterate
+ [2] => validate
+ [3] => cache
+
+Before we dive into configuring features, let us explain modularization basics.
+
+.. include:: ../daemon/bindings/modules.rst
+
+Now you know what configuration file to modify, how to read examples and what modules are so you are ready for a real configuration work!
+
+.. _`Learn Lua in 15 minutes`: http://tylerneylon.com/a/learn-lua/
+
--- /dev/null
+.. _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-priming
+ modules-rfc7706
+ modules-prefill
+ modules-serve_stale
+ modules-edns_keepalive
+
--- /dev/null
+*****************************************
+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.
+
+.. toctree::
+ :maxdepth: 1
+
+ modules-hints
+ modules-policy
+ modules-view
+ modules-daf
+ modules-rebinding
+ modules-refuse_nord
+ modules-dns64
+ modules-renumber
+ config-answer-reordering
+
+++ /dev/null
-.. _config-syntax:
-
-Files, syntax, basics
-=====================
-
-Configuration file is named ``/etc/knot-resolver/kresd.conf`` and is read when you execute Knot Resolver using systemd commands described in section :ref:`startup`. [#]_
-
-The configuration file syntax allows you to specify different kinds of data:
-
- - ``group.option = 123456``
- - ``group.option = "string value"``
- - ``group.command(123456, "string value")``
- - ``group.command({ key1 = "value1", key2 = 222, key3 = "third value" })``
- - ``globalcommand(a_parameter_1, a_parameter_2, a_parameter_3, etc)``
- - ``-- any text after -- sign is ignored till end of line``
-
-Following **configuration file snippet** starts listening for unencrypted and also encrypted DNS queries on IP address 192.0.2.1, and sets cache size.
-
-.. code-block:: lua
-
- -- this is a comment: listen for unencrypted queries
- net.listen('192.0.2.1')
- -- another comment: listen for queries encrypted using TLS on port 853
- net.listen('192.0.2.1', 853, { kind = 'tls' })
- -- 10 MB cache is suitable for a very small deployment
- cache.size = 10 * MB
-
-.. tip::
- When copy&pasting examples from this manual please pay close
- attention to brackets and also line ordering - order of lines matters.
-
- The configuration language is in fact Lua script, so you can use full power
- of this programming language. See article
- `Learn Lua in 15 minutes`_ for a syntax overview.
-
-When you modify configuration file on disk restart resolver process to get changes into effect. See chapter `Zero-downtime restarts`_ if even short outages are not acceptable for your deployment.
-
-.. [#] If you decide to run binary ``/usr/sbin/kresd`` manually (instead of using systemd) do not forget to specify ``-c`` option with path to configuration file, otherwise ``kresd`` will read file named ``config`` from its current working directory.
-
-Besides text configuration file, Knot Resolver also supports interactive and dynamic configuration using scripts or external systems, which is described in chapter :ref:`runtime-cfg`. Through this manual we present examples for both usage types - static configuration in a text file (see above) and also the interactive mode.
-
-The **interactive prompt** is denoted by ``>``, so all examples starting with ``>`` character are transcripts of user (or script) interaction with Knot Resolver and resolver's responses. For example:
-
-.. code-block:: lua
-
- > -- this is a comment entered into interactive prompt
- > -- comments have no effect here
- > -- the next line shows a command entered interactivelly and its output
- > verbose()
- false
- > -- the previous line without > character is output from verbose() command
-
-Following example demontrates how to interactivelly list all currently loaded modules, and includes multi-line output:
-
-.. code-block:: lua
-
- > modules.list()
- [1] => iterate
- [2] => validate
- [3] => cache
-
-One last thing before we dive into configuring features:
-
-.. 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!
-
-.. include:: ../daemon/README.rst
-.. include:: ../daemon/lua/trust_anchors.rst
-
-Networking and protocols
-========================
-.. include:: ../daemon/bindings/net.rst
-.. include:: ../daemon/bindings/net_tlssrv.rst
-.. include:: ../modules/http/README.rst
-.. include:: ../modules/http/README.doh.rst
-
-Logging, monitoring, diagnostics
-================================
-Knot Resolver logs to standard outputs, which is then captured by supervisor
-and sent to logging system for further processing.
-To read logs use commands usual for your distribution.
-E.g. on distributions using systemd-journald use command ``journalctl -u kresd@* -f``.
-
-During normal operation only errors and other very important events are logged,
-so by default logs from Knot Resolver should contain only couple lines a day.
-For debugging purposes it is possible to enable very verbose logging using
-:func:`verbose` function.
-
-.. function:: verbose([true | false])
-
- :param: ``true`` to enable, ``false`` to disable verbose logging.
- :return: boolean Current state of verbose logging.
-
- Toggle global verbose logging. Use only for debugging purposes.
- On busy systems vebose logging can produce several MB of logs per
- second and will slow down operation.
-
-Less verbose logging for DNSSEC validation errors can be enabled using :ref:`mod-bogus_log` module.
-
-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.
-
-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`.
-
-.. contents::
- :depth: 1
- :local:
-
-.. include:: ../modules/nsid/README.rst
-
-.. include:: ../modules/stats/README.rst
-.. .. subchapter of stats module
-.. include:: ../modules/graphite/README.rst
-.. .. subchapter of stats module
-.. include:: ../modules/http/prometheus.rst
-
-.. include:: ../modules/dnstap/README.rst
-.. include:: ../modules/watchdog/README.rst
-.. include:: ../modules/bogus_log/README.rst
-.. include:: ../modules/http/trace.rst
-.. include:: ../modules/ta_sentinel/README.rst
-.. include:: ../modules/ta_signal_query/README.rst
-.. include:: ../modules/detect_time_skew/README.rst
-.. include:: ../modules/detect_time_jump/README.rst
-
-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.
-
-.. contents::
- :depth: 1
- :local:
-
-.. include:: ../modules/hints/README.rst
-.. include:: ../modules/policy/README.rst
-.. include:: ../modules/view/README.rst
-.. include:: ../modules/daf/README.rst
-.. include:: ../modules/rebinding/README.rst
-.. include:: ../modules/refuse_nord/README.rst
-.. include:: ../modules/dns64/README.rst
-.. include:: ../modules/renumber/README.rst
-
-Answer reordering
------------------
-Certain clients are "dumb" and always connect to first IP address or name found
-in a DNS answer received from resolver intead of picking randomly.
-As a workaround for such broken clients it is possible to randomize
-order of records in DNS answers sent by resolver:
-
-.. function:: reorder_RR([true | false])
-
- :param boolean new_value: ``true`` to enable or ``false`` to disable randomization *(optional)*
- :return: The (new) value of the option
-
- If set, resolver will vary the order of resource records within RR sets.
- It is disabled by default.
-
-
-.. _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 `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.
-
-.. include:: ../daemon/bindings/cache.rst
-.. include:: ../systemd/multiinst.rst
-.. include:: ../modules/predict/README.rst
-.. include:: ../modules/priming/README.rst
-.. include:: ../modules/rfc7706.rst
-.. include:: ../modules/prefill/README.rst
-.. include:: ../modules/serve_stale/README.rst
-.. include:: ../modules/edns_keepalive/README.rst
-
-Experimental features
-=====================
-.. include:: ../modules/experimental_dot_auth/README.rst
-
-.. include:: ../daemon/scripting.rst
-
-
--- /dev/null
+../daemon/bindings/cache.rst
\ No newline at end of file
--- /dev/null
+../daemon/bindings/net_client.rst
\ No newline at end of file
--- /dev/null
+../daemon/bindings/net_dns_tweaks.rst
\ No newline at end of file
--- /dev/null
+../daemon/bindings/net_server.rst
\ No newline at end of file
--- /dev/null
+../daemon/bindings/net_tlssrv.rst
\ No newline at end of file
--- /dev/null
+../daemon/scripting.rst
\ No newline at end of file
.. toctree::
:caption: Quick Start
:name: quickstart
- :maxdepth: 2
+ :maxdepth: 1
- startguide
+ quickstart-install
+ quickstart-startup
+ quickstart-config
.. toctree::
:caption: Configuration
:name: users
:maxdepth: 2
- config
-
+ config-overview
+ config-network
+ config-dnssec
+ config-logging-monitoring
+ config-policy
+ config-performance
+ config-experimental
.. _operation:
--- /dev/null
+../modules/bogus_log/README.rst
\ No newline at end of file
--- /dev/null
+../modules/daf/README.rst
\ No newline at end of file
--- /dev/null
+../modules/detect_time_jump/README.rst
\ No newline at end of file
--- /dev/null
+../modules/detect_time_skew/README.rst
\ No newline at end of file
--- /dev/null
+../modules/dns64/README.rst
\ No newline at end of file
--- /dev/null
+../modules/dnstap/README.rst
\ No newline at end of file
--- /dev/null
+../modules/edns_keepalive/README.rst
\ No newline at end of file
--- /dev/null
+../modules/experimental_dot_auth/README.rst
\ No newline at end of file
--- /dev/null
+../modules/graphite/README.rst
\ No newline at end of file
--- /dev/null
+../modules/hints/README.rst
\ No newline at end of file
--- /dev/null
+../modules/http/README.doh.rst
\ No newline at end of file
--- /dev/null
+../modules/http/prometheus.rst
\ No newline at end of file
--- /dev/null
+../modules/http/trace.rst
\ No newline at end of file
--- /dev/null
+../modules/http/README.rst
\ No newline at end of file
--- /dev/null
+../modules/nsid/README.rst
\ No newline at end of file
--- /dev/null
+../modules/policy/README.rst
\ No newline at end of file
--- /dev/null
+../modules/predict/README.rst
\ No newline at end of file
--- /dev/null
+../modules/prefill/README.rst
\ No newline at end of file
--- /dev/null
+../modules/priming/README.rst
\ No newline at end of file
--- /dev/null
+../modules/rebinding/README.rst
\ No newline at end of file
--- /dev/null
+../modules/refuse_nord/README.rst
\ No newline at end of file
--- /dev/null
+../modules/renumber/README.rst
\ No newline at end of file
--- /dev/null
+../modules/rfc7706.rst
\ No newline at end of file
--- /dev/null
+../modules/serve_stale/README.rst
\ No newline at end of file
--- /dev/null
+../modules/stats/README.rst
\ No newline at end of file
--- /dev/null
+../modules/ta_sentinel/README.rst
\ No newline at end of file
--- /dev/null
+../modules/ta_signal_query/README.rst
\ No newline at end of file
--- /dev/null
+../modules/view/README.rst
\ No newline at end of file
--- /dev/null
+../modules/watchdog/README.rst
\ No newline at end of file
-.. _startguide:
-
-Welcome to Knot Resolver Quick Start Guide! This chapter will guide you through first installation and basic setup recommended for your use-case.
-
-Before we start let us explain basic conventions used in this text:
-
-This is Linux/Unix shell command to be executed and an output from this command:
-
-.. code-block:: bash
-
- $ echo "This is output!"
- This is output!
- $ echo "We use sudo to execute commands as root:"
- We use sudo to execute commands as root:
- $ sudo id
- uid=0(root) gid=0(root) groups=0(root)
-
-Snippets from Knot Resolver's configuration file **do not start with $ sign** and look like this:
-
-.. code-block:: lua
-
- -- this is a comment
- -- following line will start listening on IP address 192.0.2.1 port 53
- net.listen('192.0.2.1')
-
-
-************
-Installation
-************
-
-As a first step add following repositories with the **latest version** of Knot Resolver. Please note that the packages available in distribution's repositories are often outdated, especially in Debian and Ubuntu repositories, and this guide might not work with their old versions.
-
-**Arch Linux**
-
-Use
-`knot-resolver <https://aur.archlinux.org/packages/knot-resolver/>`_
-package from AUR_.
-
-**CentOS**
-
-.. code-block:: bash
-
- $ sudo yum install -y https://secure.nic.cz/files/knot-resolver/knot-resolver-release.el.rpm
- $ sudo yum install -y knot-resolver
-
-**Debian/Ubuntu**
-
-.. code-block:: bash
-
- $ wget https://secure.nic.cz/files/knot-resolver/knot-resolver-release.deb
- $ sudo dpkg -i knot-resolver-release.deb
- $ sudo apt update
- $ sudo apt install -y knot-resolver
-
-**Fedora**
-
-.. code-block:: bash
-
- $ sudo dnf install -y https://secure.nic.cz/files/knot-resolver/knot-resolver-release.fedora.rpm
- $ sudo dnf install -y knot-resolver
-
-**OpenSUSE Leap / Tumbleweed**
-
-Add the `OBS <https://en.opensuse.org/Portal:Build_Service>`_ package repository `home:CZ-NIC:knot-resolver-latest <https://build.opensuse.org/package/show/home:CZ-NIC:knot-resolver-latest/knot-resolver>`_ to your system.
-
-
-.. _startup:
-
-*******
-Startup
-*******
-
-The simplest way to run single instance of
-Knot Resolver is to use provided Knot Resolver's Systemd integration:
-
-.. code-block:: bash
-
- $ sudo systemctl start kresd@1.service
-
-See logs and status of running instance with ``systemctl status kresd@1.service`` command. For more information about Systemd integration see ``man kresd.systemd``.
-
-.. warning::
-
- ``kresd@*.service`` is not enabled by default, thus Knot Resolver won't start automatically after reboot.
- To start and enable service in one command use ``systemctl enable --now kresd@1.service``
-
-First DNS query
-===============
-After installation and first startup, Knot Resolver's default configuration accepts queries on loopback interface. This allows you to test that the installation and service startup were successful before continuing with configuration.
-
-For instance, you can use DNS lookup utility ``kdig`` to send DNS queries. The ``kdig`` command is provided by following packages:
-
-============ =================
-Distribution package with kdig
-============ =================
-Arch knot
-CentOS knot-utils
-Debian knot-dnsutils
-Fedora knot-utils
-OpenSUSE knot-utils
-Ubuntu knot-dnsutils
-============ =================
-
-The following query should return list of Root Name Servers:
-
-.. code-block:: bash
-
- $ kdig +short @localhost . NS
- a.root-servers.net.
- ...
- m.root-servers.net.
-
+.. _quickstart-config:
*************
Configuration
For this reason we recommend all users to use full VPN instead of encrypting *just* DNS queries.
Following configuration is provided **only for users who cannot encrypt all their traffic**.
For more information please see following articles:
-
+
- Simran Patil and Nikita Borisov. 2019. What can you learn from an IP? (`slides <https://irtf.org/anrw/2019/slides-anrw19-final44.pdf>`_, `the article itself <https://dl.acm.org/authorize?N687437>`_)
- `Bert Hubert. 2019. Centralised DoH is bad for Privacy, in 2019 and beyond <https://labs.ripe.net/Members/bert_hubert/centralised-doh-is-bad-for-privacy-in-2019-and-beyond>`_
See chapter :ref:`cache_persistence`.
-**********
-Next steps
-**********
-Congratulations! Your resolver is now up and running and ready for queries. For serious deployments do not forget to read :ref:`operation` chapter.
+.. raw:: html
+ <h2>Next steps</h2>
+Congratulations! Your resolver is now up and running and ready for queries. For serious deployments do not forget to read :ref:`operation` chapter.
-.. _SNI: https://en.wikipedia.org/wiki/Server_Name_Indication
-.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository
.. _`Learn Lua in 15 minutes`: http://tylerneylon.com/a/learn-lua/
.. _`DNS Privacy Test Servers`: https://dnsprivacy.org/wiki/display/DP/DNS+Privacy+Test+Servers
-.. _lua-filesystem: https://keplerproject.github.io/luafilesystem//manual.html#reference
-.. _KnotDNS: https://www.knot-dns.cz/
.. _tmpfs: https://en.wikipedia.org/wiki/Tmpfs
--- /dev/null
+.. _quickstart-intro:
+
+Welcome to Knot Resolver Quick Start Guide! This chapter will guide you through first installation and basic setup recommended for your use-case.
+
+Before we start let us explain basic conventions used in this text:
+
+This is Linux/Unix shell command to be executed and an output from this command:
+
+.. code-block:: bash
+
+ $ echo "This is output!"
+ This is output!
+ $ echo "We use sudo to execute commands as root:"
+ We use sudo to execute commands as root:
+ $ sudo id
+ uid=0(root) gid=0(root) groups=0(root)
+
+Snippets from Knot Resolver's configuration file **do not start with $ sign** and look like this:
+
+.. code-block:: lua
+
+ -- this is a comment
+ -- following line will start listening on IP address 192.0.2.1 port 53
+ net.listen('192.0.2.1')
+
+
+.. _quickstart-install:
+
+************
+Installation
+************
+
+As a first step add following repositories with the **latest version** of Knot Resolver. Please note that the packages available in distribution's repositories are often outdated, especially in Debian and Ubuntu repositories, and this guide might not work with their old versions.
+
+**Arch Linux**
+
+Use
+`knot-resolver <https://aur.archlinux.org/packages/knot-resolver/>`_
+package from AUR_.
+
+**CentOS 7**
+
+.. code-block:: bash
+
+ $ sudo yum install -y https://secure.nic.cz/files/knot-resolver/knot-resolver-release.el.rpm
+ $ sudo yum install -y knot-resolver
+
+**Debian/Ubuntu**
+
+.. code-block:: bash
+
+ $ wget https://secure.nic.cz/files/knot-resolver/knot-resolver-release.deb
+ $ sudo dpkg -i knot-resolver-release.deb
+ $ sudo apt update
+ $ sudo apt install -y knot-resolver
+
+**Fedora**
+
+.. code-block:: bash
+
+ $ sudo dnf install -y https://secure.nic.cz/files/knot-resolver/knot-resolver-release.fedora.rpm
+ $ sudo dnf install -y knot-resolver
+
+**OpenSUSE Leap / Tumbleweed**
+
+Add the `OBS <https://en.opensuse.org/Portal:Build_Service>`_ package repository `home:CZ-NIC:knot-resolver-latest <https://build.opensuse.org/package/show/home:CZ-NIC:knot-resolver-latest/knot-resolver>`_ to your system.
+
+.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository
--- /dev/null
+.. _quickstart-startup:
+
+*******
+Startup
+*******
+
+The simplest way to run single instance of
+Knot Resolver is to use provided Knot Resolver's Systemd integration:
+
+.. code-block:: bash
+
+ $ sudo systemctl start kresd@1.service
+
+See logs and status of running instance with ``systemctl status kresd@1.service`` command. For more information about Systemd integration see ``man kresd.systemd``.
+
+.. warning::
+
+ ``kresd@*.service`` is not enabled by default, thus Knot Resolver won't start automatically after reboot.
+ To start and enable service in one command use ``systemctl enable --now kresd@1.service``
+
+First DNS query
+===============
+After installation and first startup, Knot Resolver's default configuration accepts queries on loopback interface. This allows you to test that the installation and service startup were successful before continuing with configuration.
+
+For instance, you can use DNS lookup utility ``kdig`` to send DNS queries. The ``kdig`` command is provided by following packages:
+
+============ =================
+Distribution package with kdig
+============ =================
+Arch knot
+CentOS knot-utils
+Debian knot-dnsutils
+Fedora knot-utils
+OpenSUSE knot-utils
+Ubuntu knot-dnsutils
+============ =================
+
+The following query should return list of Root Name Servers:
+
+.. code-block:: bash
+
+ $ kdig +short @localhost . NS
+ a.root-servers.net.
+ ...
+ m.root-servers.net.
--- /dev/null
+../systemd/multiinst.rst
\ No newline at end of file
.. _mod-bogus_log:
DNSSEC validation failure logging
----------------------------------
+=================================
This module adds error message for each DNSSEC validation failure.
It is meant to provide hint to operators which queries should be
.. _mod-cookies:
DNS Cookies
------------
+===========
The module performs most of the :rfc:`7873` DNS cookies functionality. Its main purpose is to check the cookies of inbound queries and responses. It is also used to alter the behaviour of the cookie functionality.
Example Configuration
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
.. code-block:: lua
.. warning:: The module must be loaded before any other module that has direct influence on query processing and response generation. The module must be able to intercept an incoming query before the processing of the actual query starts. It must also be able to check the cookies of inbound responses and eventually discard them before they are handled by other functional units.
Properties
-^^^^^^^^^^
+----------
.. function:: cookies.config(configuration)
The function may be called without any parameter. In such case it only returns current configuration. The returned JSON also contains available algorithm choices.
Dependencies
-^^^^^^^^^^^^
+------------
* `Nettle <https://www.lysator.liu.se/~nisse/nettle/>`_ required for HMAC-SHA256
.. _mod-daf:
DNS Application Firewall
-------------------------
+========================
This module is a high-level interface for other powerful filtering modules and DNS views. It provides an easy interface to apply and monitor DNS filtering rules and a persistent memory for them. It also provides a restful service interface and an HTTP interface.
Example configuration
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
Firewall rules are declarative and consist of filters and actions. Filters have ``field operator operand`` notation (e.g. ``qname = example.com``), and may be chained using AND/OR keywords. Actions may or may not have parameters after the action name.
}
Web interface
-^^^^^^^^^^^^^
+-------------
If you have :ref:`HTTP/2 <mod-http>` loaded, the firewall automatically loads as a snippet.
You can create, track, suspend and remove firewall rules from the web interface.
If you load both modules, you have to load `daf` after `http`.
RESTful interface
-^^^^^^^^^^^^^^^^^
+-----------------
The module also exports a RESTful API for operations over rule chains.
.. _mod-detect_time_jump:
Detect discontinuous jumps in the system time
----------------------------------------------
+=============================================
This module detect discontinuous jumps in the system time when resolver
is running. It clears cache when a significant backward time jumps occurs.
.. _mod-detect_time_skew:
System time skew detector
--------------------------
+=========================
This module compares local system time with inception and expiration time
bounds in DNSSEC signatures for ``. NS`` records. If the local system time is
.. _mod-dns64:
DNS64
------
+=====
The module for :rfc:`6147` DNS64 AAAA-from-A record synthesis, it is used to enable client-server communication between an IPv6-only client and an IPv4-only server. See the well written `introduction`_ in the PowerDNS documentation.
If no address is passed (i.e. ``nil``), the well-known prefix ``64:ff9b::`` is used.
.. tip:: The A record sub-requests will be DNSSEC secured, but the synthetic AAAA records can't be. Make sure the last mile between stub and resolver is secure to avoid spoofing.
Example configuration
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
.. code-block:: lua
.. _mod-dnstap:
Dnstap
-------
+======
The ``dnstap`` module supports logging DNS responses to a unix socket
in dnstap_ format using fstrm framing library.
.. _mod-edns_keepalive:
EDNS keepalive
---------------
+==============
The ``edns_keepalive`` module implements :rfc:`7828` for *clients* connecting to Knot Resolver via TCP and TLS.
Note that client connections are timed-out the same way *regardless* of them sending the EDNS option;
.. _mod-experimental_dot_auth:
Experimental DNS-over-TLS Auto-discovery
-----------------------------------------
+========================================
This experimental module provides automatic discovery of authoritative servers' supporting DNS-over-TLS.
The module uses magic NS names to detect SPKI_ fingerprint which is very similar to `dnscurve`_ mechanism.
.. warning:: This protocol and module is experimental and can be changed or removed at any time. Use at own risk, security properties were not analyzed!
How it works
-^^^^^^^^^^^^
+------------
The module will look for NS target names formatted as:
``dot-{base32(sha256(SPKI))}....``
converted to base64 translates to ``m+12GgMFIiheEhKvUcOynjbn3WYQUp5tVGDh7Snwj/Q=``.
Generating NS target names
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------
To generate the NS target name, use the following command to generate the base32 encoded string of the SPKI fingerprint:
...
Example configuration
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
To enable the module, add this snippet to your config:
This module requires standard ``basexx`` Lua library which is typically provided by ``lua-basexx`` package.
Caveats
-^^^^^^^
+-------
The module relies on seeing the reply of the NS query and as such will not work
if Knot Resolver uses data from its cache. You may need to delete the cache before starting ``kresd`` to work around this.
The module also assumes that the NS query answer will return both the NS targets in the Authority section as well as the glue records in the Additional section.
Dependencies
-^^^^^^^^^^^^
+------------
* `lua-basexx <https://github.com/aiq/basexx>`_ available in LuaRocks
.. _mod-graphite:
Graphite/InfluxDB/Metronome
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+===========================
The ``graphite`` sends statistics over the Graphite_ protocol to either Graphite_, Metronome_, InfluxDB_ or any compatible storage. This allows powerful visualization over metrics collected by Knot Resolver.
}
}
-Dependencies:
+Dependencies
+------------
* `lua cqueues <https://25thandclement.com/~william/projects/cqueues.html>`_ package.
.. _mod-hints:
Static hints
-------------
+============
This is a module providing static hints for forward records (A/AAAA) and reverse records (PTR).
The records can be loaded from ``/etc/hosts``-like files and/or added directly.
drops out of cache.
Examples
-^^^^^^^^
+--------
.. code-block:: lua
That can be worked around e.g. by explicit ``policy.PASS`` action.
Properties
-^^^^^^^^^^
+----------
.. function:: hints.config([path])
.. _mod-http-doh:
DNS-over-HTTP (DoH)
--------------------
+===================
.. warning::
Make sure you read through this chapter before exposing the DoH service to users.
DoH support in Knot Resolver
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------
The :ref:`HTTP module <mod-http>` in Knot Resolver also provides support for
binary DNS-over-HTTP protocol standardized in :rfc:`8484`.
Alternative configurations use HTTP proxies between clients and a Knot Resolver instance:
Normal HTTP proxy
-^^^^^^^^^^^^^^^^^
+-----------------
:Scenario:
A standard HTTP-compliant proxy is configured to proxy `GET`
and `POST` requests to HTTP endpoint `/doh` to a machine
- More complicated setup with two components (proxy + Knot Resolver).
HTTP proxy with DoH support
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
:Scenario:
HTTP proxy extended with a
`special module for DNS-over-HTTP <https://github.com/facebookexperimental/doh-proxy>`_.
- More complicated setup with three components (proxy + special module + Knot Resolver).
Client configuration
-^^^^^^^^^^^^^^^^^^^^
+--------------------
Most common client today is web browser Firefox. Relevant configuration is described e.g. in following
`article <https://www.internetsociety.org/blog/2018/12/dns-privacy-support-in-mozilla-firefox/>`_.
To use your own DoH server just change ``network.trr.uri`` configuration option
.. _mod-http:
HTTP/2 services
----------------
+===============
This module does the heavy lifting to provide an HTTP/2 enabled
server which provides few built-in services and also allows other
.. _mod-http-example:
Example configuration
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
This section shows how to configure HTTP module itself. For information how
to configure HTTP server's IP addresses and ports please see chapter
.. _mod-http-tls:
HTTPS (TLS for HTTP)
-^^^^^^^^^^^^^^^^^^^^
+--------------------
By default, the web interface starts HTTPS/2 on specified port using an ephemeral
TLS certificate that is valid for 90 days and is automatically renewed. It is of
.. _mod-http-built-in-services:
Built-in services
-^^^^^^^^^^^^^^^^^
+-----------------
The HTTP module has several built-in services to use.
.. _mod-http-custom-endpoint:
How to expose custom services over HTTP
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------------------
Each kind of endpoint provides table of HTTP endpoints, and the default table
can be replaced using ``http.config()`` configuration call
http.snippets['/health'] = {'Health service', '<p>UP!</p>'}
How to expose custom RESTful services
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------------------
A RESTful service is likely to respond differently to different type of methods and requests,
there are three things that you can do in a service handler to send back results.
end
Dependencies
-^^^^^^^^^^^^
+------------
* `lua-http <https://github.com/daurnimator/lua-http>`_ (>= 0.3) available in LuaRocks
.. _mod-http-prometheus:
Prometheus metrics endpoint
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+===========================
The `HTTP module <mod-http>`_ exposes ``/metrics`` endpoint that serves metrics
from :ref:`mod-stats` in Prometheus_ text format.
table.insert(metrics, 'build_info{version="1.2.3"} 1')
end
+.. _Prometheus: https://prometheus.io
.. _mod-http-trace:
Tracing requests
-----------------
+================
The `HTTP module <mod-http>`_ provides ``/trace`` endpoint which allows to trace various
aspects of the request execution. The basic mode allows you to resolve a query
.. _mod-nsid:
Name Server Identifier (NSID)
------------------------------
+=============================
Module ``nsid`` 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 `multiple instances`_, anycast or load balancers).
+(e.g. when using :ref:`systemd-multiple-instances`, anycast or load balancers).
NSID value can be configured in the resolver's configuration file:
.. _mod-policy:
Query policies
---------------
+==============
This module can block, rewrite, or alter inbound queries based on user-defined policies.
Filters
-^^^^^^^
+-------
A *filter* selects which queries will be affected by specified *action*. There are several policy filters available in the ``policy.`` table:
* ``all(action)``
.. _mod-policy-actions:
Actions
-^^^^^^^
+-------
An *action* is function which modifies DNS query, and is either of type *chain* or *non-chain*. So-called *chain* actions modify the query and allow other rules to evaluate and modify the same query. *Non-chain* actions have opposite behavior, i.e. modify the query and stop rule processing.
Resolver comes with several actions available in the ``policy.`` table:
-**Non-chain actions**
+Non-chain actions
+^^^^^^^^^^^^^^^^^
Following actions stop the policy matching on the query, i.e. other rules are not evaluated once rule with following actions matches:
``FORWARD``, ``TLS_FORWARD`` and ``STUB`` support up to four IP addresses "in a single call".
-**Chain actions**
+Chain actions
+^^^^^^^^^^^^^
Following actions allow to keep trying to match other rules, until a non-chain action is triggered:
.. _tls-forwarding:
Forwarding over TLS protocol (DNS-over-TLS)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------------------------
Policy `TLS_FORWARD` allows you to forward queries using `Transport Layer Security`_ protocol, which hides the content of your queries from an attacker observing the network traffic. Further details about this protocol can be found in :rfc:`7858` and `IETF draft dprive-dtls-and-tls-profiles`_.
Queries affected by `TLS_FORWARD` policy will always be resolved over TLS connection. Knot Resolver does not implement fallback to non-TLS connection, so if TLS connection cannot be established or authenticated according to the configuration, the resolution will fail.
When multiple servers are specified, the one with the lowest round-trip time is used.
CA+hostname authentication
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^
Traditional PKI authentication requires server to present certificate with specified hostname, which is issued by one of trusted CAs. Example policy is:
.. code-block:: lua
A list of paths is also accepted, but all of them must be valid PEMs.
Key-pinned authentication
-~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^
Instead of CAs, you can specify hashes of accepted certificates in ``pin_sha256``.
They are in the usual format -- base64 from sha256.
You may still specify ``hostname`` if you want SNI_ to be sent.
.. _tls-examples:
TLS Examples
-~~~~~~~~~~~~
+^^^^^^^^^^^^
.. code-block:: lua
})
Forwarding to multiple targets
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
With the use of :any:`policy.slice` function, it is possible to split the
entire DNS namespace into distinct slices. When used in conjuction with
.. _policy_examples:
Policy examples
-^^^^^^^^^^^^^^^
+---------------
.. code-block:: lua
Replacing part of the DNS tree
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------------
You may want to resolve most of the DNS namespace by usual means while letting some other resolver solve specific subtrees.
Such data would typically be rejected by DNSSEC validation starting from the ICANN root keys. Therefore, if you trust the resolver and your link to it, you can simply use the ``STUB`` action instead of ``FORWARD`` to avoid validation only for those subtrees.
Additional properties
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
Most properties (actions, filters) are described above.
.. _mod-predict:
Prefetching records
--------------------
+===================
The module refreshes records that are about to expire when they're used (having less than 1% of original TTL).
This improves latency for frequently used records, as they are fetched in advance.
.. tip:: The tracking window and period length determine memory requirements. If you have a server with relatively fast query turnover, keep the period low (hour for start) and shorter tracking window (5 minutes). For personal slower resolver, keep the tracking window longer (i.e. 30 minutes) and period longer (a day), as the habitual queries occur daily. Experiment to get the best results.
Example configuration
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
.. code-block:: lua
.. note:: Otherwise this module requires :ref:`stats <mod-stats>` module and loads it if not present.
Exported metrics
-^^^^^^^^^^^^^^^^
+----------------
To visualize the efficiency of the predictions, the module exports following statistics.
Properties
-^^^^^^^^^^
+----------
.. function:: predict.config({ window = 15, period = 24})
.. _mod-prefill:
Cache prefilling
-----------------
+================
This module provides ability to periodically prefill DNS cache by importing root zone data obtained over HTTPS.
Only root zone import is supported at the moment.
Dependencies
-^^^^^^^^^^^^
+------------
Depends on the prefill-lua-http_ and luafilesystem_ libraries.
.. _mod-priming:
Priming module
---------------
+==============
The module for Initializing a DNS Resolver with Priming Queries implemented
according to :rfc:`8109`. Purpose of the module is to keep up-to-date list of
.. _mod-rebinding:
Rebinding protection
---------------------
+====================
This module provides protection from `DNS Rebinding attack`_ by blocking
answers which cointain IPv4_ or IPv6_ addresses for private use
.. _mod-refuse_nord:
Refuse queries without RD bit
------------------------------
+=============================
This module ensures all queries without RD (recursion desired) bit set in query
are answered with REFUSED. This prevents snooping on the resolver's cache content.
.. _mod-renumber:
Renumber
---------
+========
The module renumbers addresses in answers to different address space.
e.g. you can redirect malicious addresses to a blackhole, or use private address ranges
.. warning:: While requests are still validated using DNSSEC, the signatures are stripped from final answer. The reason is that the address synthesis breaks signatures. You can see whether an answer was valid or not based on the AD flag.
Example configuration
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
.. code-block:: lua
.. _mod-serve_stale:
Serve stale
------------
+===========
Demo module that allows using timed-out records in case kresd is
unable to contact upstream servers.
See also the RFC draft_ (not fully followed) and :any:`cache.ns_tout`.
Running
-^^^^^^^
+-------
.. code-block:: lua
modules = { 'serve_stale < cache' }
.. _mod-stats:
Statistics collector
---------------------
+====================
Module ``stats`` gathers various counters from the query resolution
and server internals, and offers them as a key-value storage.
exposed as :ref:`mod-http-prometheus`, or processed using user-provided script
as described in chapter :ref:`async-events`.
-.. note::
-
- Please remember that each Knot Resolver instance keeps its own statistics, and instances can be started and stopped dynamically. This might affect your data postprocessing procedures if you are using `Multiple instances`_.
+.. note:: Please remember that each Knot Resolver instance keeps its own
+ statistics, and instances can be started and stopped dynamically. This might
+ affect your data postprocessing procedures if you are using
+ :ref:`systemd-multiple-instances`.
.. _mod-stats-list:
Built-in statistics
-^^^^^^^^^^^^^^^^^^^
+-------------------
Built-in counters keep track of number of queries and answers matching specific criteria.
5
Module reference
-^^^^^^^^^^^^^^^^
+----------------
.. function:: stats.get(key)
.. _mod-ta_sentinel:
Sentinel for Detecting Trusted Root Keys
-----------------------------------------
+========================================
The module ``ta_sentinel`` implements A Root Key Trust Anchor Sentinel for DNSSEC
according to standard :rfc:`8509`.
.. _mod-ta_signal_query:
Signaling Trust Anchor Knowledge in DNSSEC
-------------------------------------------
+==========================================
The module for Signaling Trust Anchor Knowledge in DNSSEC Using Key Tag Query,
implemented according to :rfc:`8145#section-5`.
.. _mod-view:
Views and ACLs
---------------
+==============
The :ref:`policy <mod-policy>` module implements policies for global query matching, e.g. solves "how to react to certain query".
This module combines it with query source matching, e.g. "who asked the query". This allows you to create personalized blacklists, filters and ACLs.
Example configuration
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
.. code-block:: lua
``::ffff:127.0.0.0/104`` instead of ``127.0.0.0/8``.
Rule order
-^^^^^^^^^^
+----------
The current implementation is best understood as three separate rule chains:
vanilla ``policy.add``, ``view:tsig`` and ``view:addr``.
Properties
-^^^^^^^^^^
+----------
.. function:: view:addr(subnet, rule)
.. _mod-watchdog:
Watchdog
---------
+========
This module cooperates with Systemd watchdog to restart the process in case
the internal event loop gets stuck. The upstream Systemd unit files are configured
set -o errexit -o nounset
+rm -rf doc/html
${SPHINX} -W -b html -d doc/.doctrees doc doc/html
+.. _systemd-multiple-instances:
+
Multiple instances
-------------------
+==================
Knot Resolver can utilize multiple CPUs running in multiple independent instances (processes), where each process utilizes at most single CPU core on your machine. If your machine handles a lot of DNS traffic run multiple instances.
For more details see ``kresd.systemd(7)``.
+.. _systemd-zero-downtime-restarts:
+
Zero-downtime restarts
-^^^^^^^^^^^^^^^^^^^^^^
+----------------------
Resolver restart normally takes just miliseconds and cache content is persistent to avoid performance drop
after restart. If you want real zero-downtime restarts use `multiple instances`_ and do rolling
restart, i.e. restart only one resolver process at a time.
.. _instance-specific-configuration:
Instance-specific configuration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------------
Instances can use arbitraty identifiers for the instances, for example we can name instances like `dns1`, `tls` and so on.
Garbage Collector
-^^^^^^^^^^^^^^^^^
+-----------------
Knot Resolver employs a separate garbage collector daemon which periodically trims the cache to keep its size below size limit configured using :envvar:`cache.size`.
projects / thirdparty / knot-resolver.git / commitdiff
