]> git.ipfire.org Git - thirdparty/knot-resolver.git/commitdiff
docs: config: network subsection
authorAleš Mrázek <ales.mrazek@nic.cz>
Wed, 12 Jul 2023 14:01:40 +0000 (16:01 +0200)
committerVladimír Čunát <vladimir.cunat@nic.cz>
Tue, 8 Aug 2023 06:50:52 +0000 (08:50 +0200)
doc/config-network-client.rst [new file with mode: 0644]
doc/config-network-dns-tweaks.rst [new file with mode: 0644]
doc/config-network-forwarding.rst
doc/config-network-server-tls.rst [new file with mode: 0644]
doc/config-network-server.rst [new file with mode: 0644]
doc/config-network.rst
doc/index.rst

diff --git a/doc/config-network-client.rst b/doc/config-network-client.rst
new file mode 100644 (file)
index 0000000..1c5eda1
--- /dev/null
@@ -0,0 +1,34 @@
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+IPv4 and IPv6 usage
+-------------------
+
+Following settings affect client part of the resolver,
+i.e. communication between the resolver itself and other DNS servers.
+
+IPv4 and IPv6 protocols are used by default. For performance reasons it is
+recommended to explicitly disable protocols which are not available
+on your system, though the impact of IPv6 outage is lowered since release 5.3.0.
+
+
+.. option:: network/do-ipv4: true|false
+
+   :default: true
+
+   Enable/disable using IPv4 for contacting upstream nameservers.
+
+.. option:: network/do-ipv6: true|false
+
+   :default: true
+
+   Enable/disable using IPv6 for contacting upstream nameservers.
+
+.. option:: network/out-interface-v4: <IPv4 address>
+
+   The IPv4 address used to perform queries.
+   Not configured by default, which lets the OS choose any address.
+
+.. option:: network/out-interface-v6: <IPv6 address>
+
+   The IPv6 address used to perform queries.
+   Not configured by default, which lets the OS choose any address.
diff --git a/doc/config-network-dns-tweaks.rst b/doc/config-network-dns-tweaks.rst
new file mode 100644 (file)
index 0000000..0e3151e
--- /dev/null
@@ -0,0 +1,47 @@
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+DNS protocol tweaks
+-------------------
+
+Following settings change low-level details of DNS protocol implementation.
+Default values should not be changed except for very special cases.
+
+.. option:: network/edns-buffer-size: <options>
+
+   Maximum EDNS payload size advertised in DNS packets.
+   Different values can be configured for communication downstream (towards clients) and upstream (towards other DNS servers).
+
+   .. option:: upstream <size B|K|M|G>
+
+      :default: 1232B
+
+   .. option:: downstream <size B|K|M|G>
+
+      :default: 1232B
+
+   Default 1232 bytes was chosen to minimize risk of `issues caused by IP fragmentation <https://blog.apnic.net/2019/07/12/its-time-to-consider-avoiding-ip-fragmentation-in-the-dns/>`_.
+   Further details can be found at `DNS Flag Day 2020 <https://www.dnsflagday.net/2020/>`_ web site.
+
+   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 by DNSSEC standard :rfc:`4035`.
+
+   .. code-block:: yaml
+
+      network:
+        edns-buffer-size:
+          upstream: 4096B
+          downstream: 1232B
+
+.. .. include:: ../modules/workarounds/README.rst
+
+.. option:: options/violators-workarounds: true|false
+
+   :default: false
+
+   Workarounds resolve behavior on specific broken sub-domains.
+   Currently it mainly disables case randomization.
+
+   .. code-block:: yaml
+
+      options:
+         violators-workarounds: true
index 1da0997e64f614563d847ade8b0df95aba0da4f1..72d37327a7a79df83c70f3bb46a0c1da706ea106 100644 (file)
@@ -3,36 +3,41 @@
 Forwarding
 ----------
 
-*Forwarding* configuration instructs resolver to forward cache-miss queries from clients to manually specified DNS resolvers *(upstream servers)*. In other words the *forwarding* mode does exact opposite of the default *recursive* mode because resolver in *recursive* mode automatically selects which servers to ask.
+*Forwarding* configuration instructs resolver to forward cache-miss queries from clients to manually specified DNS resolvers *(upstream servers)*.
+In other words the *forwarding* mode does exact opposite of the default *recursive* mode because resolver in *recursive* mode automatically selects which servers to ask.
 
 Main use-cases are:
 
-  - Building a tree structure of DNS resolvers to improve performance (by improving cache hit rate).
-  - Accessing domains which are not available using recursion (e.g. if internal company servers return different answers than public ones).
-  - Forwarding through a central DNS traffic filter.
+  * Building a tree structure of DNS resolvers to improve performance (by improving cache hit rate).
+  * Accessing domains which are not available using recursion (e.g. if internal company servers return different answers than public ones).
+  * Forwarding through a central DNS traffic filter.
 
 Forwarding implementation in Knot Resolver has following properties:
 
-  - Answers from *upstream* servers are cached.
-  - Answers from *upstream* servers are locally DNSSEC-validated, unless :func:`policy.STUB` is used.
-  - Resolver automatically selects which IP address from given set of IP addresses will be used (based on performance characteristics).
-  - Forwarding can use either unencrypted DNS protocol, or :ref:`tls-forwarding`.
+  * Answers from *upstream* servers are cached.
+  * Answers from *upstream* servers are locally DNSSEC-validated, unless dnssec is disabled.
+  * Resolver automatically selects which IP address from given set of IP addresses will be used (based on performance characteristics).
+  * Forwarding can use either unencrypted DNS protocol, or :ref:`config-policy-forwarding-tls`.
 
 .. warning::
 
-        We strongly discourage use of "fake top-level domains" like ``corp.`` because these made-up domains are indistinguishable from an attack, so DNSSEC validation will prevent such domains from working. If you *really* need a variant of forwarding which does not DNSSEC-validate received data please see chapter :ref:`dns-graft`. In long-term it is better to migrate data into a legitimate, properly delegated domains which do not suffer from these security problems.
+        We strongly discourage use of "fake top-level domains" like ``corp.`` because these made-up domains are indistinguishable from an attack, so DNSSEC validation will prevent such domains from working.
+        If you *really* need a variant of forwarding which does not DNSSEC-validate received data please see chapter :ref:`dns-graft`.
+        In long-term it is better to migrate data into a legitimate, properly delegated domains which do not suffer from these security problems.
 
 
 Simple examples for **unencrypted** forwarding:
 
-.. code-block:: lua
+.. code-block:: yaml
 
-        -- forward all traffic to specified IP addresses (selected automatically)
-        policy.add(policy.all(policy.FORWARD({'2001:db8::1', '192.0.2.1'})))
+   forward:
+     # forward all traffic to specified IP addresses (selected automatically)
+     - subtree: "."
+       servers: [2001:db8::1, 192.0.2.1]
+     # forward only queries for names under domain example.com to a single IP address
+     - subtree: example.com.
+       servers: [192.0.2.1]
 
-        -- forward only queries for names under domain example.com to a single IP address
-        policy.add(policy.suffix(policy.FORWARD('192.0.2.1'), {todname('example.com.')}))
+To configure encrypted version please see chapter :ref:`config-policy-forwarding-tls`.
 
-To configure encrypted version please see chapter :ref:`tls-forwarding`.
-
-Forwarding is documented in depth together with rest of :ref:`mod-policy`.
+Forwarding is documented in depth together with rest of :ref:`config-policy`.
diff --git a/doc/config-network-server-tls.rst b/doc/config-network-server-tls.rst
new file mode 100644 (file)
index 0000000..75175d4
--- /dev/null
@@ -0,0 +1,192 @@
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _config-network-server-tls:
+
+DoT and DoH (encrypted DNS)
+---------------------------
+
+.. warning::
+
+   It is important to understand **limits of encrypting only DNS traffic**.
+   Relevant security analysis can be found in article
+   *Simran Patil and Nikita Borisov. 2019. What can you learn from an IP?*
+   See `slides <https://irtf.org/anrw/2019/slides-anrw19-final44.pdf>`_
+   or `the article itself <https://dl.acm.org/authorize?N687437>`_.
+
+DoT and DoH encrypt DNS traffic with Transport Layer Security (TLS) protocol
+and thus protects DNS traffic from certain types of attacks.
+
+You can learn more about DoT and DoH and their implementation in Knot Resolver
+in `this article
+<https://en.blog.nic.cz/2020/11/25/encrypted-dns-in-knot-resolver-dot-and-doh/>`_.
+
+.. _dns-over-tls:
+
+DNS-over-TLS (DoT)
+^^^^^^^^^^^^^^^^^^
+
+DNS-over-TLS server (:rfc:`7858`) can be configured using ``dot`` kind in
+:option:`network/listen <network/listen: <list>>`.  It is enabled on localhost by default.
+
+For certificate configuration, refer to :ref:`dot-doh-config-options`.
+
+.. _dns-over-https:
+
+DNS-over-HTTPS (DoH)
+^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+   Knot Resolver currently offers two DoH implementations.
+   It is recommended to use this new implementation, which is more reliable, scalable and has fewer dependencies.
+   Make sure to use ``doh2`` kind in :option:`network/listen <network/listen: <list>>` to select this implementation.
+
+.. tip::
+
+   Independent information about political controversies around the
+   DoH deployment by default can be found in blog posts `DNS Privacy at IETF
+   104 <http://www.potaroo.net/ispcol/2019-04/angst.html>`_ and `More DOH
+   <http://www.potaroo.net/ispcol/2019-04/moredoh.html>`_ by Geoff Huston and
+   `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>`_
+   by Bert Hubert.
+
+DNS-over-HTTPS server (:rfc:`8484`) can be configured using ``doh2`` kind in
+:option:`network/listen <network/listen: <list>>`.
+
+This implementation supports HTTP/2 (:rfc:`7540`). Queries can be sent to the
+``/dns-query`` endpoint, e.g.:
+
+.. code-block:: bash
+
+       $ kdig @127.0.0.1 +https www.knot-resolver.cz AAAA
+
+**Only TLS version 1.3 (or higher) is supported with DNS-over-HTTPS.**
+The additional considerations for TLS 1.2 required by HTTP/2 are not implemented (:rfc:`7540#section-9.2`).
+
+.. warning::
+
+   Take care when configuring your server to listen on well known HTTPS port.
+   If an unrelated HTTPS service is running on the same port with REUSEPORT enabled, you will end up with both services malfunctioning.
+
+
+.. _dot-doh-config-options:
+
+HTTP status codes
+"""""""""""""""""
+
+As specified by :rfc:`8484`, the resolver responds with status **200 OK** whenever
+it can produce a valid DNS reply for a given query, even in cases where the DNS
+``rcode`` indicates an error (like ``NXDOMAIN``, ``SERVFAIL``, etc.).
+
+For DoH queries malformed at the HTTP level, the resolver may respond with
+the following status codes:
+
+ * **400 Bad Request** for a generally malformed query, like one not containing
+   a valid DNS packet
+ * **404 Not Found** when an incorrect HTTP endpoint is queried - the only
+   supported ones are ``/dns-query`` and ``/doh``
+ * **413 Payload Too Large** when the DNS query exceeds its maximum size
+ * **415 Unsupported Media Type** when the query's ``Content-Type`` header
+   is not ``application/dns-message``
+ * **431 Request Header Fields Too Large** when a header in the query is too
+   large to process
+ * **501 Not Implemented** when the query uses a method other than
+   ``GET``, ``POST``, or ``HEAD``
+
+
+Configuration options for DoT and DoH
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+   These settings affect both DNS-over-TLS and DNS-over-HTTPS (including the legacy implementation).
+
+A self-signed certificate is generated by default.
+For serious deployments it is strongly recommended to configure your own TLS certificates signed by a trusted CA.
+
+.. option:: network/tls:
+
+   .. option:: cert-file: <path>
+
+   .. option:: key-file: <path>
+
+   .. code-block:: yaml
+
+      network:
+        tls:
+          cert-file: /etc/knot-resolver/server-cert.pem
+          key-file: /etc/knot-resolver/server-key.pem
+
+   .. tip::
+
+      The certificate files aren't automatically reloaded on change.
+      If you update the certificate files, e.g. using ACME, you have to either
+      reload or restart the service(s).
+
+   .. option:: sticket-secret: <str>
+
+      Optional, secret for TLS session resumption via tickets, by :rfc:`5077`.
+
+      The server-side key is rotated roughly once per hour.
+      By default or if called without secret, the key is random.
+      That is good for long-term forward secrecy, but multiple :ref:`workers <config-multiple-workers>`
+      won't be able to resume each other's sessions.
+
+      If you provide the same secret to multiple workers, they will be able to resume
+      each other's sessions *without* any further communication between them.
+      This synchronization works only among instances having the same endianness
+      and time_t structure and size (`sizeof(time_t)`).
+
+      **For good security** the secret must have enough entropy to be hard to guess,
+      and it should still be occasionally rotated manually and securely forgotten,
+      to reduce the scope of privacy leak in case the
+      `secret leaks eventually <pfs_>`_.
+
+      .. warning::
+
+         **Setting the secret is probably too risky with TLS <= 1.2 and GnuTLS < 3.7.5**.
+         GnuTLS 3.7.5 adds an option to disable resumption via tickets for TLS <= 1.2, enabling them only for protocols that do guarantee
+         `PFS <pfs_>`_. Knot Resolver makes use of this new option when linked against GnuTLS >= 3.7.5.
+
+   .. option:: sticket-secret-file: <path>
+
+      The same as :option:`sticket-secret <sticket-secret: <str>>`, except the secret is read from a (binary) file.
+
+   .. option:: padding: true|false|<0-512>
+
+      :default: true
+
+      EDNS(0) padding of answers to queries that arrive over TLS
+      transport.  If set to ``true`` (the default), it will use a sensible
+      default padding scheme, as implemented by libknot if available at
+      compile time.  If set to a numeric value >= 2 it will pad the
+      answers to nearest *padding* boundary, e.g. if set to ``64``, the
+      answer will have size of a multiple of 64 (64, 128, 192, ...).  If
+      set to ``false`` (or a number < 2), it will disable padding entirely.
+
+.. Configuration options for DoH
+.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. .. function:: net.doh_headers([string or table of strings])
+
+..    Selects the headers to be exposed. These headers and their values are
+..    available in ``request.qsource.headers``. Comparison
+..    is case-insensitive and pseudo-headers are supported as well.
+
+..    The following snippet can be used in the lua module to access headers
+..    ``:method`` and ``user-agent``:
+
+..    .. code-block:: lua
+
+..       net.doh_headers({':method', 'user-agent'})
+
+..       ...
+
+..       for i = 1, tonumber(req.qsource.headers.len) do
+..         local name = ffi.string(req.qsource.headers.at[i - 1].name)
+..         local value = ffi.string(req.qsource.headers.at[i - 1].value)
+..         print(name, value)
+..       end
+
+.. _pfs: https://en.wikipedia.org/wiki/Forward_secrecy
diff --git a/doc/config-network-server.rst b/doc/config-network-server.rst
new file mode 100644 (file)
index 0000000..e4d6c63
--- /dev/null
@@ -0,0 +1,144 @@
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+Addresses and services
+----------------------
+
+Addresses, ports, protocols, and API calls available for clients communicating
+with resolver are configured in :option:`network/listen <network/listen: <list>>`.
+
+First you need to decide what service should be available on given IP address
++ port combination.
+
+.. csv-table::
+   :header: "Protocol/service", :option:`kind <kind: dns|xdp|dot|doh2|doh-legacy>`
+
+   "DNS (unencrypted UDP+TCP, :rfc:`1034`)","``dns``"
+   "DNS (unencrypted UDP, :ref:`using XDP Linux API <dns-over-xdp>`)","``xdp``"
+   ":ref:`dns-over-tls`","``dot``"
+   ":ref:`dns-over-https`","``doh2``"
+   ":ref:`mod-http-doh`","``doh-legacy``"
+
+.. note::
+
+   By default, **unencrypted DNS and DNS-over-TLS** are configured to **listen on localhost**.
+
+.. option:: network/listen: <list>
+
+   .. option:: unix-socket: <path>
+
+      Path to unix domain socket to listen to.
+
+   .. option:: interface: <address or interface>
+
+      IP address or interface name to listen on, can also be a list of addresses and interface names.
+      Optionaly, the port number can be specified using ``@`` as separator, e.g. ``127.0.0.1@3535`` or ``eth0@5353``.
+
+   .. option:: port: <1-65535>
+
+      :default: 53 (dns, xdp), 853 (dot), 443 (doh2, doh-legacy)
+
+      Port number to listen to.
+
+   .. option:: kind: dns|xdp|dot|doh2|doh-legacy
+
+      :default: dns
+
+      DNS query transport protocol.
+
+   .. option:: freebind: true|false
+
+      :default: false
+
+      Freebind allows binding to a non-local or not yet available address.
+
+.. code-block:: yaml
+
+   network:
+     listen:
+       - interface: '::1'  # default port is 53
+       - interface: lo
+         port: 3535
+       - interface: eth0
+         kind: dot  # default port is 853
+       - interface: [127.0.0.1, '::1']
+         kind: doh2  # default port is 443
+       - interface: eth0
+         port: 5353  # custom port number, default is 53 for XDP
+         kind: xdp
+       - unix-socket: /tmp/kres-socket  # bind to unix domain socked
+
+.. warning::
+
+    On machines with multiple IP addresses avoid listening on wildcards ``0.0.0.0`` or ``::``. Knot Resolver could answer from different IP addresses if the network address ranges overlap, and clients would probably refuse such a response.
+
+
+.. _config-network-proxyv2:
+
+PROXYv2 protocol
+^^^^^^^^^^^^^^^^
+
+Knot Resolver supports proxies that utilize the `PROXYv2 protocol <https://www.haproxy.org/download/2.5/doc/proxy-protocol.txt>`_
+to identify clients.
+
+A PROXY header contains the IP address of the original client who sent a query.
+This allows the resolver to treat queries as if they actually came from
+the client's IP address rather than the address of the proxy they came through.
+For example, :ref:`Views and ACLs <config-views>` are able to work properly when
+PROXYv2 is in use.
+
+Since allowing usage of the PROXYv2 protocol for all clients would be a security
+vulnerability, because clients would then be able to spoof their IP addresses via
+the PROXYv2 header, the resolver requires you to specify explicitly which clients
+are allowed to send PROXYv2 headers.
+
+PROXYv2 queries from clients who are not explicitly allowed to use this protocol
+will be discarded.
+
+.. option:: network/proxy-protocol: false|<options>
+
+   :default: false
+
+   .. option:: allow: <list of addresses and subnets>
+
+      Allow usage of the PROXYv2 protocol headers by clients on the specified
+      addresses. It is possible to permit whole networks to send PROXYv2 headers
+      by specifying the network mask using the CIDR notation
+      (e.g. ``172.22.0.0/16``). IPv4 as well as IPv6 addresses are supported.
+
+      If you wish to allow all clients to use PROXYv2 (e.g. because you have this
+      kind of security handled on another layer of your network infrastructure),
+      you can specify a netmask of ``/0``. Please note that this setting is
+      address-family-specific, so this needs to be applied to both IPv4 and IPv6
+      separately.
+
+.. code-block:: yaml
+
+   network:
+     proxy-protocol:
+       allow:
+         - 172.22.0.1     # allows '172.22.0.1' specifically
+         - 172.18.1.0/24  # allows everyone at '172.18.1.*'
+         - fe80::/10      # allows everyone at IPv6 link-local
+         - '::/0'         # allows all IPv6 (but no IPv4)
+         - 0.0.0.0/0      # allows all IPv4 (but no IPv6)
+
+
+TCP pipeline limit
+^^^^^^^^^^^^^^^^^^
+
+TCP pipeline limit per-client, i.e. the number of outstanding queries that a single client connection can make in parallel.
+
+.. option:: network/tcp-pipeline: <int>
+
+    :default: 100
+
+.. code-block:: yaml
+
+   network:
+     tcp-pipeline: 50
+
+.. warning::
+
+   Please note that too large limit may have negative impact on performance and can lead to increased number of SERVFAIL answers.
+
+.. _`dnsproxy module`: https://www.knot-dns.cz/docs/2.7/html/modules.html#dnsproxy-tiny-dns-proxy
index 2faac0e36d67302e3a6c28914ad2661af372504a..8311543bb41eda352bc685471f375be28b856247 100644 (file)
@@ -1,6 +1,6 @@
 .. SPDX-License-Identifier: GPL-3.0-or-later
 
-.. _network-configuration:
+.. _config-network:
 
 ************************
 Networking and protocols
@@ -40,20 +40,20 @@ Server (communication with clients)
 .. toctree::
    :maxdepth: 2
 
-   daemon-bindings-net_server
-   daemon-bindings-net_tlssrv
-   modules-http
+   config-network-server
+   config-network-server-tls
+   .. config-network-http
 
 Client (retrieving answers from servers)
 ========================================
 
-Following chapters describe basic configuration of how resolver retrieves data from other *(upstream)* servers. Data processing is also affected by configured policies, see chapter :ref:`policies` for more advanced usage.
+Following chapters describe basic configuration of how resolver retrieves data from other *(upstream)* servers. Data processing is also affected by configured policies, see chapter :ref:`config-policy-new` for more advanced usage.
 
 .. toctree::
    :maxdepth: 2
 
-   daemon-bindings-net_client
-   config-network-forwarding
+   config-network-client
+   config-forward
 
 DNS protocol tweaks
 ===================
@@ -61,4 +61,4 @@ DNS protocol tweaks
 .. toctree::
    :maxdepth: 2
 
-   daemon-bindings-net_dns_tweaks
+   config-network-dns-tweaks
index 95a1f31fe97f84e9223bdeffcb7a4e0d642f6f59..a9b0dd69ab825bcacde2f1c775519f8b6007281f 100644 (file)
@@ -25,9 +25,9 @@ If you are a new user, please start with chapter for :ref:`getting started <gett
    :maxdepth: 3
 
    config-overview
-   usecase-network-interfaces
-   config-policy-new
+   config-network
    config-performance
+   config-policy-new
    config-logging-monitoring
    config-dnssec
    config-lua