dnsdist: Better documentation for out-of-order support

diff --git a/pdns/dnsdistdist/docs/advanced/index.rst b/pdns/dnsdistdist/docs/advanced/index.rst
index 966cab90f47365c2479c39c4d445b6531b6fee78..cd3071599593dea7d2a78030319e8495a2e7fab0 100644 (file)
--- a/pdns/dnsdistdist/docs/advanced/index.rst
+++ b/pdns/dnsdistdist/docs/advanced/index.rst
@@ -19,3 +19,4 @@ These chapters contain information on the advanced features of dnsdist
    snmp
    axfr
    multiple-instance
+   out-of-order

diff --git a/pdns/dnsdistdist/docs/advanced/out-of-order.rst b/pdns/dnsdistdist/docs/advanced/out-of-order.rst
new file mode 100644 (file)
index 0000000..d48f7d7
--- /dev/null
+++ b/pdns/dnsdistdist/docs/advanced/out-of-order.rst
@@ -0,0 +1,26 @@
+Out-of-order
+------------
+
+As of 1.6.0, dnsdist supports accepting and processing queries out-of-order as long as the
+``maxInFlight`` parameter has been set on the frontend, via :func:`addLocal` and/or :func:`addTLSLocal`.
+Note that it is always enabled on DoH frontends.
+As many as ``maxInFlight`` queries will then be read from a TCP connection, processed and forwarded
+to a backend simultaneously. If there is more queries pending, they will be processed once a response
+has been sent for one of the already processed queries.
+
+Backends are assumed not to support out-of-order by default, so only query at a time will be sent over
+a TCP connection to a backend, meaning that up to ``maxInFlight` connections to a backend might be needed
+to be able to process all accepted queries.
+Setting ``maxInFlight`` to a value greater than zero on :func:`newServer` changes that, and up to ``maxInFlight``
+queries can be sent to a backend simultaneously over the same TCP connection. This of course requires the
+backend to actually process incoming queries out-of-order, otherwise the latency will be considerably increased,
+leading to timeouts and degraded service.
+
+As of 1.6.0, only queries from the same incoming client connection will be sent to a server over a single
+outgoing TCP connections. This will likely change in 1.7.0, once we have had time to check that it has no
+adverse effects.
+
+Backends for which Proxy Protocol support has been enabled will never be able to reuse the same outgoing TCP
+connections for different clients, given that the payload indicating the source IP of the client, as seen by
+dnsdist, is sent once at the beginning of the TCP connection. For the same reason, it might not even be possible
+to reuse a TCP connection for the same client if any Type-Length-Value data has been sent over that connection.

diff --git a/pdns/dnsdistdist/docs/reference/config.rst b/pdns/dnsdistdist/docs/reference/config.rst
index e5877e233a4b646e6693722dd411f41265682659..f27ffbe80ae2cb592329f9b20bc6778c36e049b8 100644 (file)
--- a/pdns/dnsdistdist/docs/reference/config.rst
+++ b/pdns/dnsdistdist/docs/reference/config.rst
@@ -529,7 +529,7 @@ Servers
       rise=NUM,              -- Require NUM consecutive successful checks before declaring the backend up, default: 1
       useProxyProtocol=BOOL, -- Add a proxy protocol header to the query, passing along the client's IP address and port along with the original destination address and port. Default is disabled.
       reconnectOnUp=BOOL,    -- Close and reopen the sockets when a server transits from Down to Up. This helps when an interface is missing when dnsdist is started. Default is disabled.
-      maxInFlight            -- Maximum number of in-flight queries. The default is 0, which disables out-of-order processing. It should only be enabled if the backend does support out-of-order processing.
+      maxInFlight            -- Maximum number of in-flight queries. The default is 0, which disables out-of-order processing. It should only be enabled if the backend does support out-of-order processing. As of 1.6.0, out-of-order processing needs to be enabled on the frontend as well, via :func:`addLocal` and/or :func:`addTLSLocal`. Note that out-of-order is always enabled on DoH frontends.
     })
 
   :param str server_string: A simple IP:PORT string.