From: Aleš Mrázek Date: Mon, 3 Jul 2023 14:04:21 +0000 (+0200) Subject: docs: config: yaml for dnssec X-Git-Tag: v6.0.2~16^2~12 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=500a896956fed4e7a9b959a29c12a6591b046042;p=thirdparty%2Fknot-resolver.git docs: config: yaml for dnssec --- diff --git a/daemon/lua/trust_anchors.rst b/daemon/lua/trust_anchors.rst index 40f79b6ad..994465e5c 100644 --- a/daemon/lua/trust_anchors.rst +++ b/daemon/lua/trust_anchors.rst @@ -120,4 +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. -.. _lua-http: https://luarocks.org/modules/daurnimator/http +.. _lua-http: https://luarocks.org/modules/daurnimator/http \ No newline at end of file diff --git a/doc/config-dnssec-glue.rst b/doc/config-dnssec-glue.rst new file mode 100644 index 000000000..9728cfbc2 --- /dev/null +++ b/doc/config-dnssec-glue.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-3.0-or-later + +.. option:: options/glue-checking: normal|strict|permissive + + :default: normal + + The resolver strictness checking level. + + By default, resolver runs in *normal* mode. There are possibly many small adjustments + hidden behind the mode settings, but the main idea is that in *permissive* mode, the resolver + tries to resolve a name with as few lookups as possible, while in *strict* mode it spends much + more effort resolving and checking referral path. However, if majority of the traffic is covered + by DNSSEC, some of the strict checking actions are counter-productive. + + .. csv-table:: + :header: "Glue type", "Modes when it is accepted", "Example glue [#example_glue]_" + + "mandatory glue", "strict, normal, permissive", "ns1.example.org" + "in-bailiwick glue", "normal, permissive", "ns1.example2.org" + "any glue records", "permissive", "ns1.example3.net" + + .. [#example_glue] The examples show glue records acceptable from servers + authoritative for `org` zone when delegating to `example.org` zone. + Unacceptable or missing glue records trigger resolution of names listed + in NS records before following respective delegation. diff --git a/doc/config-dnssec-ta.rst b/doc/config-dnssec-ta.rst new file mode 100644 index 000000000..f05a4e79e --- /dev/null +++ b/doc/config-dnssec-ta.rst @@ -0,0 +1,107 @@ +.. SPDX-License-Identifier: GPL-3.0-or-later + +.. warning:: + + Options in this section are intended only for expert users and normally should not be needed. + +Since version 4.0, **DNSSEC validation is enabled by default**. +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. + +.. code-block:: yaml + + # turns off DNSSEC validation + dnssec: false + +The resolver supports DNSSEC including :rfc:`5011` automated DNSSEC TA updates +and :rfc:`7646` negative trust anchors. Depending on your distribution, DNSSEC +trust anchors should be either maintained in accordance with the distro-wide +policy, or automatically maintained by the resolver itself. + +In practice this means that you can forget about it and your favorite Linux +distribution will take care of it for you. + +Following :option:`dnssec` section allow to modify DNSSEC configuration *if you really have to*: + +.. option:: dnssec: false| + + DNSSEC configuration options. If ``false``, DNSSEC is disabled. + + .. option:: trust-anchors-files: + + .. option:: file: + + Path to the key file. + + .. option:: read-only: true|false + + :default: false + + Blocks zonefile updates according to :rfc:`5011`. + + The format is standard zone file, though additional information may be persisted in comments. + Either DS or DNSKEY records can be used for TAs. + If the file does not exist, bootstrapping of *root* TA will be attempted. + If you want to use bootstrapping, install `lua-http`_ library. + + Each file can only contain records for a single domain. + The TAs will be updated according to :rfc:`5011` and persisted in the file (if allowed). + + .. code-block:: yaml + + dnssec: + trust-anchors-files: + - file: root.key + read-only: false + + .. option:: hold-down-time: