From: Remi Gacogne Date: Mon, 7 Jun 2021 15:01:41 +0000 (+0200) Subject: dnsdist: Document the TCP, TLS, DoH changes X-Git-Tag: dnsdist-1.7.0-alpha1~45^2~18 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=aafe00a3304b7628390ace7651fe0bd105674d61;p=thirdparty%2Fpdns.git dnsdist: Document the TCP, TLS, DoH changes --- diff --git a/pdns/dnsdistdist/docs/advanced/internal-design.rst b/pdns/dnsdistdist/docs/advanced/internal-design.rst index 3c3f8a8ac7..6641020f4a 100644 --- a/pdns/dnsdistdist/docs/advanced/internal-design.rst +++ b/pdns/dnsdistdist/docs/advanced/internal-design.rst @@ -17,6 +17,8 @@ That design means that there is a maximum of 65535 in-flight UDP queries per bac Note that the source address and port used to contact a given backend is set at startup, for performance reasons, and then only changes on reconnect. There might be more than one socket, and thus several ports, if the ``sockets`` parameter was set to a higher value than 1 on the :func:`newServer` directive. +Note that, since 1.7.0, UDP queries can be passed to the backend over TCP if the backend is TCP-only, or configured for DNS over TLS. + TCP / DoT design ---------------- diff --git a/pdns/dnsdistdist/docs/advanced/tuning.rst b/pdns/dnsdistdist/docs/advanced/tuning.rst index 2bf9aa50a2..14b0506c1c 100644 --- a/pdns/dnsdistdist/docs/advanced/tuning.rst +++ b/pdns/dnsdistdist/docs/advanced/tuning.rst @@ -83,7 +83,7 @@ Any value larger than 0 will cause new connections to be dropped if there are al By default, every TCP worker thread has its own queue, and the incoming TCP connections are dispatched to TCP workers on a round-robin basis. This might cause issues if some connections are taking a very long time, since incoming ones will be waiting until the TCP worker they have been assigned to has finished handling its current query, while other TCP workers might be available. -The experimental :func:`setTCPUseSinglePipe` directive can be used so that all the incoming TCP connections are put into a single queue and handled by the first TCP worker available. This used to be useful before 1.4.0 because a single connection could block a TCP worker, but the "one pipe per TCP worker" is preferable now that workers can handle multiple connections to prevent waking up all idle workers when a new connection arrives. +The experimental :func:`setTCPUseSinglePipe` directive can be used so that all the incoming TCP connections are put into a single queue and handled by the first TCP worker available. This used to be useful before 1.4.0 because a single connection could block a TCP worker, but the "one pipe per TCP worker" is preferable now that workers can handle multiple connections to prevent waking up all idle workers when a new connection arrives. This option will be removed in 1.7.0. One of the first starting point when investigating TCP or DNS over TLS issues is to look at the :func:`showTCPStats` command. It provides a lot of metrics about the current and passed connections, and why they were closed. diff --git a/pdns/dnsdistdist/docs/guides/dns-over-https.rst b/pdns/dnsdistdist/docs/guides/dns-over-https.rst index 879f7e971b..662ffc86b8 100644 --- a/pdns/dnsdistdist/docs/guides/dns-over-https.rst +++ b/pdns/dnsdistdist/docs/guides/dns-over-https.rst @@ -54,13 +54,14 @@ To let dnsdist listen for DoH queries over HTTP on localhost at port 8053 add on Internal design --------------- -The internal design used for DoH handling uses two threads per :func:`addDOHLocal` directive. The first thread will handle the HTTP/2 communication with the client and pass the received DNS queries to a second thread which will apply the rules and pass the query to a backend, over **UDP**. The response will be received by the regular UDP response handler for that backend and passed back to the first thread. That allows the first thread to be low-latency dealing with TLS and HTTP/2 only and never blocking. +The internal design used for DoH handling uses two threads per :func:`addDOHLocal` directive. The first thread will handle the HTTP/2 communication with the client and pass the received DNS queries to a second thread which will apply the rules and pass the query to a backend, over **UDP** (except if the backend is TCP-only, or uses DNS over TLS). The response will be received by the regular UDP response handler for that backend and passed back to the first thread. That allows the first thread to be low-latency dealing with TLS and HTTP/2 only and never blocking. .. figure:: ../imgs/DNSDistDoH.png :align: center :alt: DNSDist DoH design The fact that the queries are forwarded over UDP means that a large UDP payload size should be configured between dnsdist and the backend to avoid most truncation issues, and dnsdist will advise a 4096-byte UDP Payload Buffer size. UDP datagrams can still be larger than the MTU as long as fragmented datagrams are not dropped on the path between dnsdist and the backend. +Since 1.7.0, truncated answers received over UDP for a DoH query will lead to a retry over TCP. Investigating issues -------------------- diff --git a/pdns/dnsdistdist/docs/reference/tuning.rst b/pdns/dnsdistdist/docs/reference/tuning.rst index 965e4f08b1..c8911c26a2 100644 --- a/pdns/dnsdistdist/docs/reference/tuning.rst +++ b/pdns/dnsdistdist/docs/reference/tuning.rst @@ -86,7 +86,7 @@ Tuning related functions .. deprecated:: 1.6.0 - Whether the incoming TCP connections should be put into a single queue instead of using per-thread queues. Defaults to false. That option was useful before 1.4.0 when a single TCP connection could block a TCP worker thread, but should not be used in recent versions where the per-thread queues model avoids waking up all idle workers when a new connection arrives. + Whether the incoming TCP connections should be put into a single queue instead of using per-thread queues. Defaults to false. That option was useful before 1.4.0 when a single TCP connection could block a TCP worker thread, but should not be used in recent versions where the per-thread queues model avoids waking up all idle workers when a new connection arrives. This option will be removed in 1.7.0. :param bool val: diff --git a/pdns/dnsdistdist/docs/running.rst b/pdns/dnsdistdist/docs/running.rst index 4158c12938..e3302ffa0e 100644 --- a/pdns/dnsdistdist/docs/running.rst +++ b/pdns/dnsdistdist/docs/running.rst @@ -52,4 +52,4 @@ Initially dnsdist tried to forward a query to the backend using the same protoco | DoH | **UDP** | +--------------+----------+ -That means that there is a potential issue with very large answers and DNS over HTTPS, requiring careful configuration of the path between dnsdist and the backend. More information about that is available in the :doc:`DNS over HTTPS section `. +Before 1.7.0, which introduced TCP fallback, that meant that there was a potential issue with very large answers and DNS over HTTPS, requiring careful configuration of the path between dnsdist and the backend. More information about that is available in the :doc:`DNS over HTTPS section `. diff --git a/pdns/dnsdistdist/docs/upgrade_guide.rst b/pdns/dnsdistdist/docs/upgrade_guide.rst index 13110e64d1..2dc77021d0 100644 --- a/pdns/dnsdistdist/docs/upgrade_guide.rst +++ b/pdns/dnsdistdist/docs/upgrade_guide.rst @@ -1,6 +1,13 @@ Upgrade Guide ============= +1.6.x to 1.7.0 +-------------- + +Truncated responses received over UDP for DoH clients will now be retried over TCP. + +:func:`setTCPUseSinglePipe` has been removed. + 1.5.x to 1.6.0 --------------