From: Charles-Henri Bruyand Date: Mon, 4 Dec 2023 08:15:35 +0000 (+0100) Subject: dnsdist: add some words about doh3 in documentation X-Git-Tag: dnsdist-1.9.0-alpha4~15^2~8 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=033e49d7a9f87a83ffcfa6b9dc963dcd71b365e1;p=thirdparty%2Fpdns.git dnsdist: add some words about doh3 in documentation --- diff --git a/pdns/dnsdist.cc b/pdns/dnsdist.cc index 4d3105a120..dd616a7d33 100644 --- 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 index 0000000000..a5c54431c2 --- /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 b5b6830508..c018ce80ad 100644 --- 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 a88ef4fa56..881d2bf688 100644 --- 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