From: Aleš Mrázek Date: Wed, 12 Jul 2023 14:01:40 +0000 (+0200) Subject: docs: config: network subsection X-Git-Tag: v6.0.2~16^2~4 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fc58503aae17893e01c228fae1763c91bee3279f;p=thirdparty%2Fknot-resolver.git docs: config: network subsection --- diff --git a/doc/config-network-client.rst b/doc/config-network-client.rst new file mode 100644 index 000000000..1c5eda1e4 --- /dev/null +++ b/doc/config-network-client.rst @@ -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: + + The IPv4 address used to perform queries. + Not configured by default, which lets the OS choose any address. + +.. option:: network/out-interface-v6: + + 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 index 000000000..0e3151eaa --- /dev/null +++ b/doc/config-network-dns-tweaks.rst @@ -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: + + 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 + + :default: 1232B + + .. option:: downstream + + :default: 1232B + + Default 1232 bytes was chosen to minimize risk of `issues caused by IP fragmentation `_. + Further details can be found at `DNS Flag Day 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 diff --git a/doc/config-network-forwarding.rst b/doc/config-network-forwarding.rst index 1da0997e6..72d37327a 100644 --- a/doc/config-network-forwarding.rst +++ b/doc/config-network-forwarding.rst @@ -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 index 000000000..75175d4ad --- /dev/null +++ b/doc/config-network-server-tls.rst @@ -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 `_ + or `the article itself `_. + +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 +`_. + +.. _dns-over-tls: + +DNS-over-TLS (DoT) +^^^^^^^^^^^^^^^^^^ + +DNS-over-TLS server (:rfc:`7858`) can be configured using ``dot`` kind in +:option:`network/listen >`. 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 >` 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 `_ and `More DOH + `_ by Geoff Huston and + `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 >`. + +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: + + .. option:: key-file: + + .. 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: + + 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 ` + 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 `_. + + .. 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 `_. Knot Resolver makes use of this new option when linked against GnuTLS >= 3.7.5. + + .. option:: sticket-secret-file: + + The same as :option:`sticket-secret >`, 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 index 000000000..e4d6c63c4 --- /dev/null +++ b/doc/config-network-server.rst @@ -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 >`. + +First you need to decide what service should be available on given IP address ++ port combination. + +.. csv-table:: + :header: "Protocol/service", :option:`kind ` + + "DNS (unencrypted UDP+TCP, :rfc:`1034`)","``dns``" + "DNS (unencrypted UDP, :ref:`using XDP Linux API `)","``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: + + .. option:: unix-socket: + + Path to unix domain socket to listen to. + + .. option:: 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 `_ +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 ` 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| + + :default: false + + .. option:: allow: + + 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: + + :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 diff --git a/doc/config-network.rst b/doc/config-network.rst index 2faac0e36..8311543bb 100644 --- a/doc/config-network.rst +++ b/doc/config-network.rst @@ -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 diff --git a/doc/index.rst b/doc/index.rst index 95a1f31fe..a9b0dd69a 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -25,9 +25,9 @@ If you are a new user, please start with chapter for :ref:`getting started