dnsdist: add some words about doh3 in documentation

diff --git a/pdns/dnsdist.cc b/pdns/dnsdist.cc
index 4d3105a1209dd536085279bbd101df839d784dab..dd616a7d33ce03dcaae6af61b3c868134361cbcf 100644 (file)
--- a/pdns/dnsdist.cc
+++ b/pdns/dnsdist.cc
@@ -2575,6 +2575,9 @@ static void reportFeatures()
 #ifdef HAVE_DNS_OVER_QUIC
   cout<<"dns-over-quic ";
 #endif
+#ifdef HAVE_DNS_OVER_HTTP3
+  cout<<"dns-over-http3 ";
+#endif
 #ifdef HAVE_DNS_OVER_TLS
   cout<<"dns-over-tls(";
 #ifdef HAVE_GNUTLS

diff --git a/pdns/dnsdistdist/docs/guides/dns-over-http3.rst b/pdns/dnsdistdist/docs/guides/dns-over-http3.rst
new file mode 100644 (file)
index 0000000..a5c5443
--- /dev/null
+++ b/pdns/dnsdistdist/docs/guides/dns-over-http3.rst
@@ -0,0 +1,23 @@
+DNS-over-HTTP/3 (DoH3)
+====================
+
+:program:`dnsdist` supports DNS-over-HTTP/3 (DoH3) for incoming queries since 1.9.0.
+To see if the installation supports this, run ``dnsdist --version``.
+If the output shows ``dns-over-http3`` incoming DNS-over-HTTP/3 is supported.
+
+Incoming
+--------
+
+Adding a listen port for DNS-over-HTTP/3 can be done with the :func:`addDOH3Local` function, e.g.::
+
+  addDOH3Local('2001:db8:1:f00::1', '/etc/ssl/certs/example.com.pem', '/etc/ssl/private/example.com.key')
+
+This will make :program:`dnsdist` listen on [2001:db8:1:f00::1]:853 on UDP, and will use the provided certificate and key to serve incoming DoH3 connections.
+
+The fourth parameter, if present, indicates various options. For instance, you can change the congestion control algorithm used. An example is::
+
+  addDOH3Local('2001:db8:1:f00::1', '/etc/ssl/certs/example.com.pem', '/etc/ssl/private/example.com.key', {congestionControlAlgo="bbr"})
+
+A particular attention should be taken to the permissions of the certificate and key files. Many ACME clients used to get and renew certificates, like CertBot, set permissions assuming that services are started as root, which is no longer true for dnsdist as of 1.5.0. For that particular case, making a copy of the necessary files in the /etc/dnsdist directory is advised, using for example CertBot's ``--deploy-hook`` feature to copy the files with the right permissions after a renewal.
+
+More information about sessions management can also be found in :doc:`../advanced/tls-sessions-management`.

diff --git a/pdns/dnsdistdist/docs/guides/index.rst b/pdns/dnsdistdist/docs/guides/index.rst
index b5b6830508bc52e0f808b5a539facf3d14d24034..c018ce80ad3a53b97a7ed06a44af4fa39a88a120 100644 (file)
--- a/pdns/dnsdistdist/docs/guides/index.rst
+++ b/pdns/dnsdistdist/docs/guides/index.rst
@@ -14,6 +14,7 @@ These chapters contain several guides and nuggets of information regarding dnsdi
    serverselection
    carbon
    dns-over-https
+   dns-over-http3
    dns-over-quic
    dns-over-tls
    dnscrypt

diff --git a/pdns/dnsdistdist/docs/reference/config.rst b/pdns/dnsdistdist/docs/reference/config.rst
index a88ef4fa561278f94c4e18c7b6f2dd7886913397..881d2bf68883b5fa8459669ce733e0830d6feb9f 100644 (file)
--- a/pdns/dnsdistdist/docs/reference/config.rst
+++ b/pdns/dnsdistdist/docs/reference/config.rst
@@ -171,6 +171,29 @@ Listen Sockets
   * ``readAhead``: bool - When the TLS provider is set to OpenSSL, whether we tell the library to read as many input bytes as possible, which leads to better performance by reducing the number of syscalls. Default is true.
   * ``proxyProtocolOutsideTLS``: bool - When the use of incoming proxy protocol is enabled, whether the payload is prepended after the start of the TLS session (so inside, meaning it is protected by the TLS layer providing encryption and authentication) or not (outside, meaning it is in clear-text). Default is false which means inside. Note that most third-party software like HAproxy expect the proxy protocol payload to be outside, in clear-text.
 
+.. function:: addDOH3Local(address, certFile(s), keyFile(s) [, options])
+
+  .. versionadded:: 1.9.0
+
+  Listen on the specified address and UDP port for incoming DNS over HTTP3 connections, presenting the specified X.509 certificate.
+
+  :param str address: The IP Address with an optional port to listen on.
+                      The default port is 853.
+  :param str certFile(s): The path to a X.509 certificate file in PEM format, a list of paths to such files, or a TLSCertificate object.
+  :param str keyFile(s): The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones. Ignored if ``certFile`` contains TLSCertificate objects.
+  :param table options: A table with key: value pairs with listen options.
+
+  Options:
+
+  * ``reusePort=false``: bool - Set the ``SO_REUSEPORT`` socket option.
+  * ``interface=""``: str - Set the network interface to use.
+  * ``cpus={}``: table - Set the CPU affinity for this listener thread, asking the scheduler to run it on a single CPU id, or a set of CPU ids. This parameter is only available if the OS provides the pthread_setaffinity_np() function.
+  * ``idleTimeout=5``: int - Set the idle timeout, in seconds.
+  * ``internalPipeBufferSize=0``: int - Set the size in bytes of the internal buffer of the pipes used internally to pass queries and responses between threads. Requires support for ``F_SETPIPE_SZ`` which is present in Linux since 2.6.35. The actual size might be rounded up to a multiple of a page size. 0 means that the OS default size is used. The default value is 0, except on Linux where it is 1048576 since 1.6.0.
+  * ``maxInFlight=0``: int - Maximum number of in-flight queries. The default is 0, which disables out-of-order processing.
+  * ``congestionControlAlgo="reno"``: str - The congestion control algorithm to be chosen between ``reno``, ``cubic`` and ``bbr``.
+  * ``keyLogFile``: str - Write the TLS keys in the specified file so that an external program can decrypt TLS exchanges, in the format described in https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format.
+
 .. function:: addDOQLocal(address, certFile(s), keyFile(s) [, options])
 
   .. versionadded:: 1.9.0