dnsdist: Document how to advertise HTTP/3 support over HTTP/2

diff --git a/pdns/dnsdistdist/docs/guides/dns-over-http3.rst b/pdns/dnsdistdist/docs/guides/dns-over-http3.rst
index 2824069ed43abbb10a91bcae9d3b86b08fc73c04..e113eabf17e2732f51991f57512977a0e6a55e96 100644 (file)
--- a/pdns/dnsdistdist/docs/guides/dns-over-http3.rst
+++ b/pdns/dnsdistdist/docs/guides/dns-over-http3.rst
@@ -1,6 +1,9 @@
 DNS-over-HTTP/3 (DoH3)
 ======================
 
+.. note::
+  This guide is about DNS over HTTP/3. For DNS over HTTP/1 and DNS over HTTP/2, please see :doc:`dns-over-https`
+
 :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.
@@ -21,3 +24,12 @@ The fourth parameter, if present, indicates various options. For instance, you c
 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`.
+
+Advertising DNS over HTTP/3 support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If DNS over HTTP/2 is also enabled in the configuration via :func:`addDOHLocal` (see :doc:`dns-over-https` for more information), it might be useful to advertise DNS over HTTP/3 support via the ``Alt-Svc`` header::
+
+  addDOHLocal('2001:db8:1:f00::1', '/etc/ssl/certs/example.com.pem', '/etc/ssl/private/example.com.key', "/dns", {customResponseHeaders={["alt-svc"]="h3\":443\""}})
+
+This will advertise that HTTP/3 is available on the same IP, port UDP/443.

diff --git a/pdns/dnsdistdist/docs/guides/dns-over-https.rst b/pdns/dnsdistdist/docs/guides/dns-over-https.rst
index eefd78864ccd36db76862b52b3bebd88bc60c265..19d38b838235670878d6c6ed02e8019f6dbf282c 100644 (file)
--- a/pdns/dnsdistdist/docs/guides/dns-over-https.rst
+++ b/pdns/dnsdistdist/docs/guides/dns-over-https.rst
@@ -1,6 +1,9 @@
 DNS-over-HTTPS (DoH)
 ====================
 
+.. note::
+  This guide is about DNS over HTTP/1 and DNS over HTTP/2. For DNS over HTTP/3, please see :doc:`dns-over-http3`
+
 :program:`dnsdist` supports DNS-over-HTTPS (DoH, standardized in RFC 8484) for incoming queries since 1.4.0, and for outgoing queries since 1.7.0.
 To see if the installation supports this, run ``dnsdist --version``.
 If the output shows ``dns-over-https(DOH)`` (``dns-over-https(h2o nghttp2)``, ``dns-over-https(h2o)`` or ``dns-over-https(nghttp2)`` since 1.9.0) , incoming DNS-over-HTTPS is supported. If ``outgoing-dns-over-https(nghttp2)`` shows up then outgoing DNS-over-HTTPS is supported.
@@ -35,6 +38,15 @@ A particular attention should be taken to the permissions of the certificate and
 
 More information about sessions management can also be found in :doc:`../advanced/tls-sessions-management`.
 
+Advertising DNS over HTTP/3 support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If DNS over HTTP/3 is also enabled in the configuration via :func:`addDOH3Local` (see :doc:`dns-over-http3` for more information), it might be useful to advertise this support via the ``Alt-Svc`` header::
+
+  addDOHLocal('2001:db8:1:f00::1', '/etc/ssl/certs/example.com.pem', '/etc/ssl/private/example.com.key', "/dns", {customResponseHeaders={["alt-svc"]="h3\":443\""}})
+
+This will advertise that HTTP/3 is available on the same IP, port UDP/443.
+
 Custom responses
 ^^^^^^^^^^^^^^^^
 

diff --git a/pdns/dnsdistdist/docs/reference/config.rst b/pdns/dnsdistdist/docs/reference/config.rst
index ebfc6b02d4d4c6bd947dbf61285a1fd091402ca6..d5d9004d1ef997c89008c373e30927895a73b81f 100644 (file)
--- a/pdns/dnsdistdist/docs/reference/config.rst
+++ b/pdns/dnsdistdist/docs/reference/config.rst
@@ -131,6 +131,7 @@ Listen Sockets
 
   Listen on the specified address and TCP port for incoming DNS over HTTPS connections, presenting the specified X.509 certificate.
   If no certificate (or key) files are specified, listen for incoming DNS over HTTP connections instead.
+  More information is available in :doc:`../guides/dns-over-https`.
 
   :param str address: The IP Address with an optional port to listen on.
                       The default port is 443.
@@ -181,6 +182,7 @@ Listen Sockets
   .. versionadded:: 1.9.0
 
   Listen on the specified address and UDP port for incoming DNS over HTTP3 connections, presenting the specified X.509 certificate.
+  More information is available in :doc:`../guides/dns-over-http3`.
 
   :param str address: The IP Address with an optional port to listen on.
                       The default port is 853.