diff options
92 files changed, 625 insertions, 482 deletions
diff --git a/daemon/README.rst b/daemon/README.rst index 59f76755..4701e8d4 100644 --- a/daemon/README.rst +++ b/daemon/README.rst @@ -35,7 +35,6 @@ TODO: Basics .. _`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 diff --git a/daemon/bindings/cache.rst b/daemon/bindings/cache.rst index cf388912..52b66b60 100644 --- a/daemon/bindings/cache.rst +++ b/daemon/bindings/cache.rst @@ -1,8 +1,9 @@ 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 @@ -12,7 +13,7 @@ against some types of Random Subdomain Attacks. .. _`cache_sizing`: Sizing -^^^^^^ +------ For personal and small office use-cases cache size around 100 MB is more than enough. @@ -39,7 +40,7 @@ Now you can configure cache size to be 90% of the free memory 14 928 MB, i.e. 13 .. _`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 @@ -80,7 +81,7 @@ size in the config file as well. .. _tmpfs: https://en.wikipedia.org/wiki/Tmpfs Configuration reference -^^^^^^^^^^^^^^^^^^^^^^^ +----------------------- .. function:: cache.open(max_size[, config_uri]) diff --git a/daemon/bindings/modules.rst b/daemon/bindings/modules.rst index 9e7c5ea1..6910b3de 100644 --- a/daemon/bindings/modules.rst +++ b/daemon/bindings/modules.rst @@ -1,5 +1,6 @@ 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. diff --git a/daemon/bindings/net_client.rst b/daemon/bindings/net_client.rst new file mode 100644 index 00000000..23b1605b --- /dev/null +++ b/daemon/bindings/net_client.rst @@ -0,0 +1,27 @@ +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. + diff --git a/daemon/bindings/net_dns_tweaks.rst b/daemon/bindings/net_dns_tweaks.rst new file mode 100644 index 00000000..017ad52c --- /dev/null +++ b/daemon/bindings/net_dns_tweaks.rst @@ -0,0 +1,22 @@ +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 diff --git a/daemon/bindings/net.rst b/daemon/bindings/net_server.rst index 7ce1083b..34b9bb23 100644 --- a/daemon/bindings/net.rst +++ b/daemon/bindings/net_server.rst @@ -1,7 +1,7 @@ .. _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 @@ -17,7 +17,8 @@ Most notable examples of such systems are CentOS 7 and macOS. 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. @@ -161,7 +162,8 @@ is unlikely. 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. @@ -208,7 +210,8 @@ Examples: 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: @@ -285,50 +288,5 @@ Following commands are useful in special situations and can be usef with and wit .. 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 diff --git a/daemon/bindings/net_tlssrv.rst b/daemon/bindings/net_tlssrv.rst index 699cc943..b59c26ce 100644 --- a/daemon/bindings/net_tlssrv.rst +++ b/daemon/bindings/net_tlssrv.rst @@ -1,7 +1,8 @@ .. _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`. diff --git a/daemon/lua/trust_anchors.rst b/daemon/lua/trust_anchors.rst index b57583ad..7788000c 100644 --- a/daemon/lua/trust_anchors.rst +++ b/daemon/lua/trust_anchors.rst @@ -1,13 +1,8 @@ -.. _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. @@ -125,7 +120,4 @@ Following functions allow to modify DNSSEC configuration *if you really have to* 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 diff --git a/daemon/scripting.rst b/daemon/scripting.rst index 543f7ce4..2524a752 100644 --- a/daemon/scripting.rst +++ b/daemon/scripting.rst @@ -14,11 +14,11 @@ Control sockets --------------- 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 diff --git a/doc/_static/logo-negativ.svg b/doc/_static/logo-negativ.svg new file mode 100644 index 00000000..ec6c90f1 --- /dev/null +++ b/doc/_static/logo-negativ.svg @@ -0,0 +1,40 @@ +<?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> diff --git a/doc/conf.py b/doc/conf.py index 0296a91f..5736d2aa 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -25,7 +25,7 @@ master_doc = 'index' # 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) @@ -56,6 +56,11 @@ htmlhelp_basename = 'apidoc' 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 diff --git a/doc/config-answer-reordering.rst b/doc/config-answer-reordering.rst new file mode 100644 index 00000000..9a165283 --- /dev/null +++ b/doc/config-answer-reordering.rst @@ -0,0 +1,15 @@ +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. + diff --git a/doc/config-dnssec.rst b/doc/config-dnssec.rst new file mode 100644 index 00000000..0da31343 --- /dev/null +++ b/doc/config-dnssec.rst @@ -0,0 +1,18 @@ +.. _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 diff --git a/doc/config-experimental.rst b/doc/config-experimental.rst new file mode 100644 index 00000000..e0c9ce45 --- /dev/null +++ b/doc/config-experimental.rst @@ -0,0 +1,12 @@ +********************* +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 diff --git a/doc/config-logging-monitoring.rst b/doc/config-logging-monitoring.rst new file mode 100644 index 00000000..4e8dc55c --- /dev/null +++ b/doc/config-logging-monitoring.rst @@ -0,0 +1,46 @@ +******************************** +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 diff --git a/doc/config-network.rst b/doc/config-network.rst new file mode 100644 index 00000000..6b5201a1 --- /dev/null +++ b/doc/config-network.rst @@ -0,0 +1,15 @@ +************************ +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 diff --git a/doc/config-overview.rst b/doc/config-overview.rst new file mode 100644 index 00000000..fc217512 --- /dev/null +++ b/doc/config-overview.rst @@ -0,0 +1,83 @@ +********************** +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/ + diff --git a/doc/config-performance.rst b/doc/config-performance.rst new file mode 100644 index 00000000..bb72346c --- /dev/null +++ b/doc/config-performance.rst @@ -0,0 +1,33 @@ +.. _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 + diff --git a/doc/config-policy.rst b/doc/config-policy.rst new file mode 100644 index 00000000..3a1c786b --- /dev/null +++ b/doc/config-policy.rst @@ -0,0 +1,20 @@ +***************************************** +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 + diff --git a/doc/config.rst b/doc/config.rst deleted file mode 100644 index ec850b74..00000000 --- a/doc/config.rst +++ /dev/null @@ -1,195 +0,0 @@ -.. _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 - - diff --git a/doc/daemon-bindings-cache.rst b/doc/daemon-bindings-cache.rst new file mode 120000 index 00000000..d5d3ee7b --- /dev/null +++ b/doc/daemon-bindings-cache.rst @@ -0,0 +1 @@ +../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 new file mode 120000 index 00000000..c96fc76f --- /dev/null +++ b/doc/daemon-bindings-net_client.rst @@ -0,0 +1 @@ +../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 new file mode 120000 index 00000000..ee7e98ac --- /dev/null +++ b/doc/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/daemon-bindings-net_server.rst b/doc/daemon-bindings-net_server.rst new file mode 120000 index 00000000..b6cf46ce --- /dev/null +++ b/doc/daemon-bindings-net_server.rst @@ -0,0 +1 @@ +../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 new file mode 120000 index 00000000..2e38daa3 --- /dev/null +++ b/doc/daemon-bindings-net_tlssrv.rst @@ -0,0 +1 @@ +../daemon/bindings/net_tlssrv.rst
\ No newline at end of file diff --git a/doc/daemon-scripting.rst b/doc/daemon-scripting.rst new file mode 120000 index 00000000..482b759e --- /dev/null +++ b/doc/daemon-scripting.rst @@ -0,0 +1 @@ +../daemon/scripting.rst
\ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst index 786c93e0..cac125b5 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -9,17 +9,24 @@ and it provides a state-machine like API for extensions. .. 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: diff --git a/doc/modules-bogus_log.rst b/doc/modules-bogus_log.rst new file mode 120000 index 00000000..61ead500 --- /dev/null +++ b/doc/modules-bogus_log.rst @@ -0,0 +1 @@ +../modules/bogus_log/README.rst
\ No newline at end of file diff --git a/doc/modules-daf.rst b/doc/modules-daf.rst new file mode 120000 index 00000000..7715ed64 --- /dev/null +++ b/doc/modules-daf.rst @@ -0,0 +1 @@ +../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 new file mode 120000 index 00000000..28214822 --- /dev/null +++ b/doc/modules-detect_time_jump.rst @@ -0,0 +1 @@ +../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 new file mode 120000 index 00000000..f0c0d149 --- /dev/null +++ b/doc/modules-detect_time_skew.rst @@ -0,0 +1 @@ +../modules/detect_time_skew/README.rst
\ No newline at end of file diff --git a/doc/modules-dns64.rst b/doc/modules-dns64.rst new file mode 120000 index 00000000..792753a7 --- /dev/null +++ b/doc/modules-dns64.rst @@ -0,0 +1 @@ +../modules/dns64/README.rst
\ No newline at end of file diff --git a/doc/modules-dnstap.rst b/doc/modules-dnstap.rst new file mode 120000 index 00000000..f77d78ec --- /dev/null +++ b/doc/modules-dnstap.rst @@ -0,0 +1 @@ +../modules/dnstap/README.rst
\ No newline at end of file diff --git a/doc/modules-edns_keepalive.rst b/doc/modules-edns_keepalive.rst new file mode 120000 index 00000000..ec7a3589 --- /dev/null +++ b/doc/modules-edns_keepalive.rst @@ -0,0 +1 @@ +../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 new file mode 120000 index 00000000..c5bbfdc5 --- /dev/null +++ b/doc/modules-experimental_dot_auth.rst @@ -0,0 +1 @@ +../modules/experimental_dot_auth/README.rst
\ No newline at end of file diff --git a/doc/modules-graphite.rst b/doc/modules-graphite.rst new file mode 120000 index 00000000..29d7c2a4 --- /dev/null +++ b/doc/modules-graphite.rst @@ -0,0 +1 @@ +../modules/graphite/README.rst
\ No newline at end of file diff --git a/doc/modules-hints.rst b/doc/modules-hints.rst new file mode 120000 index 00000000..16063101 --- /dev/null +++ b/doc/modules-hints.rst @@ -0,0 +1 @@ +../modules/hints/README.rst
\ No newline at end of file diff --git a/doc/modules-http-doh.rst b/doc/modules-http-doh.rst new file mode 120000 index 00000000..317d0e1f --- /dev/null +++ b/doc/modules-http-doh.rst @@ -0,0 +1 @@ +../modules/http/README.doh.rst
\ No newline at end of file diff --git a/doc/modules-http-prometheus.rst b/doc/modules-http-prometheus.rst new file mode 120000 index 00000000..5f9ac97b --- /dev/null +++ b/doc/modules-http-prometheus.rst @@ -0,0 +1 @@ +../modules/http/prometheus.rst
\ No newline at end of file diff --git a/doc/modules-http-trace.rst b/doc/modules-http-trace.rst new file mode 120000 index 00000000..c11fca0e --- /dev/null +++ b/doc/modules-http-trace.rst @@ -0,0 +1 @@ +../modules/http/trace.rst
\ No newline at end of file diff --git a/doc/modules-http.rst b/doc/modules-http.rst new file mode 120000 index 00000000..3fc5fec3 --- /dev/null +++ b/doc/modules-http.rst @@ -0,0 +1 @@ +../modules/http/README.rst
\ No newline at end of file diff --git a/doc/modules-nsid.rst b/doc/modules-nsid.rst new file mode 120000 index 00000000..7ea4cc77 --- /dev/null +++ b/doc/modules-nsid.rst @@ -0,0 +1 @@ +../modules/nsid/README.rst
\ No newline at end of file diff --git a/doc/modules-policy.rst b/doc/modules-policy.rst new file mode 120000 index 00000000..690a2b5d --- /dev/null +++ b/doc/modules-policy.rst @@ -0,0 +1 @@ +../modules/policy/README.rst
\ No newline at end of file diff --git a/doc/modules-predict.rst b/doc/modules-predict.rst new file mode 120000 index 00000000..a4a8424a --- /dev/null +++ b/doc/modules-predict.rst @@ -0,0 +1 @@ +../modules/predict/README.rst
\ No newline at end of file diff --git a/doc/modules-prefill.rst b/doc/modules-prefill.rst new file mode 120000 index 00000000..cfa8384a --- /dev/null +++ b/doc/modules-prefill.rst @@ -0,0 +1 @@ +../modules/prefill/README.rst
\ No newline at end of file diff --git a/doc/modules-priming.rst b/doc/modules-priming.rst new file mode 120000 index 00000000..a36c3bfc --- /dev/null +++ b/doc/modules-priming.rst @@ -0,0 +1 @@ +../modules/priming/README.rst
\ No newline at end of file diff --git a/doc/modules-rebinding.rst b/doc/modules-rebinding.rst new file mode 120000 index 00000000..a8e9d016 --- /dev/null +++ b/doc/modules-rebinding.rst @@ -0,0 +1 @@ +../modules/rebinding/README.rst
\ No newline at end of file diff --git a/doc/modules-refuse_nord.rst b/doc/modules-refuse_nord.rst new file mode 120000 index 00000000..22e585cf --- /dev/null +++ b/doc/modules-refuse_nord.rst @@ -0,0 +1 @@ +../modules/refuse_nord/README.rst
\ No newline at end of file diff --git a/doc/modules-renumber.rst b/doc/modules-renumber.rst new file mode 120000 index 00000000..1764c78a --- /dev/null +++ b/doc/modules-renumber.rst @@ -0,0 +1 @@ +../modules/renumber/README.rst
\ No newline at end of file diff --git a/doc/modules-rfc7706.rst b/doc/modules-rfc7706.rst new file mode 120000 index 00000000..11b5c3d8 --- /dev/null +++ b/doc/modules-rfc7706.rst @@ -0,0 +1 @@ +../modules/rfc7706.rst
\ No newline at end of file diff --git a/doc/modules-serve_stale.rst b/doc/modules-serve_stale.rst new file mode 120000 index 00000000..98fa5318 --- /dev/null +++ b/doc/modules-serve_stale.rst @@ -0,0 +1 @@ +../modules/serve_stale/README.rst
\ No newline at end of file diff --git a/doc/modules-stats.rst b/doc/modules-stats.rst new file mode 120000 index 00000000..c8c5583e --- /dev/null +++ b/doc/modules-stats.rst @@ -0,0 +1 @@ +../modules/stats/README.rst
\ No newline at end of file diff --git a/doc/modules-ta_sentinel.rst b/doc/modules-ta_sentinel.rst new file mode 120000 index 00000000..669e5a4e --- /dev/null +++ b/doc/modules-ta_sentinel.rst @@ -0,0 +1 @@ +../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 new file mode 120000 index 00000000..15e5d67f --- /dev/null +++ b/doc/modules-ta_signal_query.rst @@ -0,0 +1 @@ +../modules/ta_signal_query/README.rst
\ No newline at end of file diff --git a/doc/modules-view.rst b/doc/modules-view.rst new file mode 120000 index 00000000..da228331 --- /dev/null +++ b/doc/modules-view.rst @@ -0,0 +1 @@ +../modules/view/README.rst
\ No newline at end of file diff --git a/doc/modules-watchdog.rst b/doc/modules-watchdog.rst new file mode 120000 index 00000000..ac7d5477 --- /dev/null +++ b/doc/modules-watchdog.rst @@ -0,0 +1 @@ +../modules/watchdog/README.rst
\ No newline at end of file diff --git a/doc/startguide.rst b/doc/quickstart-config.rst index 427373bb..231d9bd0 100644 --- a/doc/startguide.rst +++ b/doc/quickstart-config.rst @@ -1,115 +1,4 @@ -.. _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 @@ -252,7 +141,7 @@ and to protect them from eavesdropping by TLS encryption. 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>`_ @@ -302,17 +191,12 @@ encryption you can move the cache to tmpfs_. 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 diff --git a/doc/quickstart-install.rst b/doc/quickstart-install.rst new file mode 100644 index 00000000..e30a5502 --- /dev/null +++ b/doc/quickstart-install.rst @@ -0,0 +1,68 @@ +.. _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 diff --git a/doc/quickstart-startup.rst b/doc/quickstart-startup.rst new file mode 100644 index 00000000..bdf313b5 --- /dev/null +++ b/doc/quickstart-startup.rst @@ -0,0 +1,45 @@ +.. _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. diff --git a/doc/systemd-multiinst.rst b/doc/systemd-multiinst.rst new file mode 120000 index 00000000..2f532708 --- /dev/null +++ b/doc/systemd-multiinst.rst @@ -0,0 +1 @@ +../systemd/multiinst.rst
\ No newline at end of file diff --git a/modules/bogus_log/README.rst b/modules/bogus_log/README.rst index 0b93e82b..629efce2 100644 --- a/modules/bogus_log/README.rst +++ b/modules/bogus_log/README.rst @@ -1,7 +1,7 @@ .. _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 diff --git a/modules/cookies/README.rst b/modules/cookies/README.rst index 5db476cf..db04c05b 100644 --- a/modules/cookies/README.rst +++ b/modules/cookies/README.rst @@ -1,12 +1,12 @@ .. _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 @@ -38,7 +38,7 @@ Example Configuration .. 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) @@ -48,7 +48,7 @@ Properties 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 diff --git a/modules/daf/README.rst b/modules/daf/README.rst index 32b69c51..7e749c3a 100644 --- a/modules/daf/README.rst +++ b/modules/daf/README.rst @@ -1,12 +1,12 @@ .. _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. @@ -80,14 +80,14 @@ If you're not sure what firewall rules are in effect, see ``daf.rules``: } 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. diff --git a/modules/detect_time_jump/README.rst b/modules/detect_time_jump/README.rst index 240907f3..13821e70 100644 --- a/modules/detect_time_jump/README.rst +++ b/modules/detect_time_jump/README.rst @@ -1,7 +1,7 @@ .. _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. diff --git a/modules/detect_time_skew/README.rst b/modules/detect_time_skew/README.rst index 8eeb2eb6..9bbba2ab 100644 --- a/modules/detect_time_skew/README.rst +++ b/modules/detect_time_skew/README.rst @@ -1,7 +1,7 @@ .. _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 diff --git a/modules/dns64/README.rst b/modules/dns64/README.rst index 047443fd..0d04ac8d 100644 --- a/modules/dns64/README.rst +++ b/modules/dns64/README.rst @@ -1,7 +1,7 @@ .. _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. @@ -13,7 +13,7 @@ If no address is passed (i.e. ``nil``), the well-known prefix ``64:ff9b::`` is u .. 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 diff --git a/modules/dnstap/README.rst b/modules/dnstap/README.rst index 19bdae8e..4b984e56 100644 --- a/modules/dnstap/README.rst +++ b/modules/dnstap/README.rst @@ -1,7 +1,7 @@ .. _mod-dnstap: Dnstap ------- +====== The ``dnstap`` module supports logging DNS responses to a unix socket in dnstap_ format using fstrm framing library. diff --git a/modules/edns_keepalive/README.rst b/modules/edns_keepalive/README.rst index 7938632b..b1c59f3e 100644 --- a/modules/edns_keepalive/README.rst +++ b/modules/edns_keepalive/README.rst @@ -1,7 +1,7 @@ .. _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; diff --git a/modules/experimental_dot_auth/README.rst b/modules/experimental_dot_auth/README.rst index d9250673..d4b62d9e 100644 --- a/modules/experimental_dot_auth/README.rst +++ b/modules/experimental_dot_auth/README.rst @@ -1,7 +1,7 @@ .. _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. @@ -9,7 +9,7 @@ The module uses magic NS names to detect SPKI_ fingerprint which is very similar .. 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))}....`` @@ -27,7 +27,7 @@ In that example, the base32 encoded (no padding) version of the sha256 PIN is `` 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: @@ -61,7 +61,7 @@ Finally, map ``dot-${b32}.a.example.com`` to the right set of IPs. ... Example configuration -^^^^^^^^^^^^^^^^^^^^^ +--------------------- To enable the module, add this snippet to your config: @@ -73,7 +73,7 @@ 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. @@ -81,7 +81,7 @@ if Knot Resolver uses data from its cache. You may need to delete the cache befo 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 diff --git a/modules/graphite/README.rst b/modules/graphite/README.rst index 415bb9e4..82cf682a 100644 --- a/modules/graphite/README.rst +++ b/modules/graphite/README.rst @@ -1,7 +1,7 @@ .. _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. @@ -35,7 +35,8 @@ The module supports sending data to multiple servers at once. } } -Dependencies: +Dependencies +------------ * `lua cqueues <https://25thandclement.com/~william/projects/cqueues.html>`_ package. diff --git a/modules/hints/README.rst b/modules/hints/README.rst index bbabe4f8..ad1e06bf 100644 --- a/modules/hints/README.rst +++ b/modules/hints/README.rst @@ -1,7 +1,7 @@ .. _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. @@ -10,7 +10,7 @@ You can also use the module to change the root hints; they are used as a safety drops out of cache. Examples -^^^^^^^^ +-------- .. code-block:: lua @@ -29,7 +29,7 @@ Examples That can be worked around e.g. by explicit ``policy.PASS`` action. Properties -^^^^^^^^^^ +---------- .. function:: hints.config([path]) diff --git a/modules/http/README.doh.rst b/modules/http/README.doh.rst index beb9657a..2edc9cef 100644 --- a/modules/http/README.doh.rst +++ b/modules/http/README.doh.rst @@ -1,7 +1,7 @@ .. _mod-http-doh: DNS-over-HTTP (DoH) -------------------- +=================== .. warning:: @@ -23,7 +23,7 @@ Following section compares several options for running a DoH capable server. 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`. @@ -58,7 +58,7 @@ Please see section :ref:`mod-http-tls` for further details about TLS configurati 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 @@ -77,7 +77,7 @@ Normal HTTP proxy - 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>`_. @@ -100,7 +100,7 @@ HTTP proxy with DoH support - 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 diff --git a/modules/http/README.rst b/modules/http/README.rst index a4816ad3..b1777143 100644 --- a/modules/http/README.rst +++ b/modules/http/README.rst @@ -1,7 +1,7 @@ .. _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 @@ -37,7 +37,7 @@ This can be changed using ``http.config()`` configuration call explained below. .. _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 @@ -64,7 +64,7 @@ Now you can reach the web services and APIs, done! .. _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 @@ -121,7 +121,7 @@ Major drawback is that current browsers won't do HTTP/2 over insecure connection .. _mod-http-built-in-services: Built-in services -^^^^^^^^^^^^^^^^^ +----------------- The HTTP module has several built-in services to use. @@ -136,7 +136,7 @@ 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 @@ -205,7 +205,7 @@ exported restful APIs and subscribe to WebSockets. 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. @@ -270,7 +270,7 @@ a response. end Dependencies -^^^^^^^^^^^^ +------------ * `lua-http <https://github.com/daurnimator/lua-http>`_ (>= 0.3) available in LuaRocks diff --git a/modules/http/prometheus.rst b/modules/http/prometheus.rst index d98a0a6c..8549de19 100644 --- a/modules/http/prometheus.rst +++ b/modules/http/prometheus.rst @@ -1,7 +1,7 @@ .. _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. @@ -40,3 +40,4 @@ You can also add custom metrics or rewrite existing metrics before they are retu table.insert(metrics, 'build_info{version="1.2.3"} 1') end +.. _Prometheus: https://prometheus.io diff --git a/modules/http/trace.rst b/modules/http/trace.rst index 72328597..cfbfb0b4 100644 --- a/modules/http/trace.rst +++ b/modules/http/trace.rst @@ -1,7 +1,7 @@ .. _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 diff --git a/modules/nsid/README.rst b/modules/nsid/README.rst index ec967d76..2b762714 100644 --- a/modules/nsid/README.rst +++ b/modules/nsid/README.rst @@ -1,13 +1,13 @@ .. _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: diff --git a/modules/policy/README.rst b/modules/policy/README.rst index 86f00d37..037b8922 100644 --- a/modules/policy/README.rst +++ b/modules/policy/README.rst @@ -1,7 +1,7 @@ .. _mod-policy: Query policies --------------- +============== This module can block, rewrite, or alter inbound queries based on user-defined policies. @@ -15,7 +15,7 @@ These rules can be overriden by action ``PASS``, see `Policy examples`_ below. Filters -^^^^^^^ +------- A *filter* selects which queries will be affected by specified *action*. There are several policy filters available in the ``policy.`` table: * ``all(action)`` @@ -37,12 +37,13 @@ A *filter* selects which queries will be affected by specified *action*. There a .. _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: @@ -60,7 +61,8 @@ Following actions stop the policy matching on the query, i.e. other rules are no ``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: @@ -78,7 +80,7 @@ Also, it is possible to write your own action (i.e. Lua function). It is possibl .. _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. @@ -94,7 +96,7 @@ To test this feature you need to either :ref:`configure Knot Resolver as DNS-ove 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 @@ -108,7 +110,7 @@ Traditional PKI authentication requires server to present certificate with speci 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. @@ -116,7 +118,7 @@ You may still specify ``hostname`` if you want SNI_ to be sent. .. _tls-examples: TLS Examples -~~~~~~~~~~~~ +^^^^^^^^^^^^ .. code-block:: lua @@ -140,7 +142,7 @@ TLS Examples }) 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 @@ -173,7 +175,7 @@ targets. .. _policy_examples: Policy examples -^^^^^^^^^^^^^^^ +--------------- .. code-block:: lua @@ -232,7 +234,7 @@ Policy examples 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. @@ -251,7 +253,7 @@ For example, if you add an alternative top-level domain while using the ICANN ro Additional properties -^^^^^^^^^^^^^^^^^^^^^ +--------------------- Most properties (actions, filters) are described above. diff --git a/modules/predict/README.rst b/modules/predict/README.rst index 6c4b442a..1f19cdcb 100644 --- a/modules/predict/README.rst +++ b/modules/predict/README.rst @@ -1,7 +1,7 @@ .. _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. @@ -13,7 +13,7 @@ ahead of time. This is helpful to minimize the perceived latency and keeps the c .. 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 @@ -32,7 +32,7 @@ Defaults are 15 minutes window, 6 hours period. .. 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. @@ -42,7 +42,7 @@ To visualize the efficiency of the predictions, the module exports following sta Properties -^^^^^^^^^^ +---------- .. function:: predict.config({ window = 15, period = 24}) diff --git a/modules/prefill/README.rst b/modules/prefill/README.rst index 1211d141..f36fec32 100644 --- a/modules/prefill/README.rst +++ b/modules/prefill/README.rst @@ -1,7 +1,7 @@ .. _mod-prefill: Cache prefilling ----------------- +================ This module provides ability to periodically prefill DNS cache by importing root zone data obtained over HTTPS. @@ -34,7 +34,7 @@ Root zone to import must be signed using DNSSEC and the resolver must have valid Only root zone import is supported at the moment. Dependencies -^^^^^^^^^^^^ +------------ Depends on the prefill-lua-http_ and luafilesystem_ libraries. diff --git a/modules/priming/README.rst b/modules/priming/README.rst index 29136849..7645dd43 100644 --- a/modules/priming/README.rst +++ b/modules/priming/README.rst @@ -1,7 +1,7 @@ .. _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 diff --git a/modules/rebinding/README.rst b/modules/rebinding/README.rst index a08b87ed..6ef11019 100644 --- a/modules/rebinding/README.rst +++ b/modules/rebinding/README.rst @@ -1,7 +1,7 @@ .. _mod-rebinding: Rebinding protection --------------------- +==================== This module provides protection from `DNS Rebinding attack`_ by blocking answers which cointain IPv4_ or IPv6_ addresses for private use diff --git a/modules/refuse_nord/README.rst b/modules/refuse_nord/README.rst index a328beed..abb91f73 100644 --- a/modules/refuse_nord/README.rst +++ b/modules/refuse_nord/README.rst @@ -1,7 +1,7 @@ .. _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. diff --git a/modules/renumber/README.rst b/modules/renumber/README.rst index 07a4a350..f5854628 100644 --- a/modules/renumber/README.rst +++ b/modules/renumber/README.rst @@ -1,7 +1,7 @@ .. _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 @@ -11,7 +11,7 @@ in local zones, that will be remapped to real addresses by the resolver. .. 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 diff --git a/modules/serve_stale/README.rst b/modules/serve_stale/README.rst index 5c681fac..b7e69947 100644 --- a/modules/serve_stale/README.rst +++ b/modules/serve_stale/README.rst @@ -1,7 +1,7 @@ .. _mod-serve_stale: Serve stale ------------ +=========== Demo module that allows using timed-out records in case kresd is unable to contact upstream servers. @@ -12,7 +12,7 @@ It's quite configurable/flexible; see the beginning of the module source for det See also the RFC draft_ (not fully followed) and :any:`cache.ns_tout`. Running -^^^^^^^ +------- .. code-block:: lua modules = { 'serve_stale < cache' } diff --git a/modules/stats/README.rst b/modules/stats/README.rst index ea62d368..02943251 100644 --- a/modules/stats/README.rst +++ b/modules/stats/README.rst @@ -1,7 +1,7 @@ .. _mod-stats: Statistics collector --------------------- +==================== Module ``stats`` gathers various counters from the query resolution and server internals, and offers them as a key-value storage. @@ -9,14 +9,15 @@ These metrics can be either exported to :ref:`mod-graphite`, 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. @@ -158,7 +159,7 @@ Example: 5 Module reference -^^^^^^^^^^^^^^^^ +---------------- .. function:: stats.get(key) diff --git a/modules/ta_sentinel/README.rst b/modules/ta_sentinel/README.rst index 5513d707..badd8914 100644 --- a/modules/ta_sentinel/README.rst +++ b/modules/ta_sentinel/README.rst @@ -1,7 +1,7 @@ .. _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`. diff --git a/modules/ta_signal_query/README.rst b/modules/ta_signal_query/README.rst index ad1b345b..836bedc8 100644 --- a/modules/ta_signal_query/README.rst +++ b/modules/ta_signal_query/README.rst @@ -1,7 +1,7 @@ .. _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`. diff --git a/modules/view/README.rst b/modules/view/README.rst index 29d79143..c352a2e3 100644 --- a/modules/view/README.rst +++ b/modules/view/README.rst @@ -1,7 +1,7 @@ .. _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. @@ -32,7 +32,7 @@ You can combine view selectors with RPZ_ to create personalized filters for exam Example configuration -^^^^^^^^^^^^^^^^^^^^^ +--------------------- .. code-block:: lua @@ -60,7 +60,7 @@ Example configuration ``::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``. @@ -75,7 +75,7 @@ By default :ref:`policy module <mod-policy>` acts before ``view`` module due to Properties -^^^^^^^^^^ +---------- .. function:: view:addr(subnet, rule) diff --git a/modules/watchdog/README.rst b/modules/watchdog/README.rst index cd2fbd03..956f0cdd 100644 --- a/modules/watchdog/README.rst +++ b/modules/watchdog/README.rst @@ -1,7 +1,7 @@ .. _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 diff --git a/scripts/make-doc.sh b/scripts/make-doc.sh index 58e5b925..6fe03806 100755 --- a/scripts/make-doc.sh +++ b/scripts/make-doc.sh @@ -12,4 +12,5 @@ fi set -o errexit -o nounset +rm -rf doc/html ${SPHINX} -W -b html -d doc/.doctrees doc doc/html diff --git a/systemd/multiinst.rst b/systemd/multiinst.rst index d9be8538..3897f5e0 100644 --- a/systemd/multiinst.rst +++ b/systemd/multiinst.rst @@ -1,5 +1,7 @@ +.. _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. @@ -29,8 +31,10 @@ With the use of brace expansion in BASH the equivalent command looks like this: 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. @@ -50,7 +54,7 @@ At any given time only a single instance is stopped and restarted so remaining t .. _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. diff --git a/utils/cache_gc/README.rst b/utils/cache_gc/README.rst index 6a3f4003..80729825 100644 --- a/utils/cache_gc/README.rst +++ b/utils/cache_gc/README.rst @@ -1,5 +1,5 @@ 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`. |
