From 6e38689a8a2ce17d89a2c800c3e6dea892694afe Mon Sep 17 00:00:00 2001 From: Remi Gacogne Date: Fri, 21 Jul 2023 17:53:34 +0200 Subject: [PATCH] dnsdist: Document the h2o -> nghttp2 upgrade path --- pdns/dnsdistdist/docs/guides/dns-over-https.rst | 12 +++++++++++- pdns/dnsdistdist/docs/install.rst | 2 +- pdns/dnsdistdist/docs/reference/config.rst | 2 +- pdns/dnsdistdist/docs/rules-actions.rst | 3 ++- pdns/dnsdistdist/docs/upgrade_guide.rst | 10 ++++++++++ 5 files changed, 25 insertions(+), 4 deletions(-) diff --git a/pdns/dnsdistdist/docs/guides/dns-over-https.rst b/pdns/dnsdistdist/docs/guides/dns-over-https.rst index 5df4d7f053..1367a99c7c 100644 --- a/pdns/dnsdistdist/docs/guides/dns-over-https.rst +++ b/pdns/dnsdistdist/docs/guides/dns-over-https.rst @@ -3,7 +3,7 @@ DNS-over-HTTPS (DoH) :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)``, incoming DNS-over-HTTPS is supported. If ``outgoing-dns-over-https(nghttp2)`` shows up then outgoing DNS-over-HTTPS is supported. +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. Incoming -------- @@ -54,6 +54,16 @@ To let dnsdist listen for DoH queries over HTTP on localhost at port 8053 add on addDOHLocal("127.0.0.1:8053") addDOHLocal("127.0.0.1:8053", nil, nil, "/", { reusePort=true }) +HTTP/1 support +^^^^^^^^^^^^^^ + +dnsdist initially relied on the ``h2o`` library to support incoming DNS over HTTPS. Since 1.9.0, ``h2o`` has been deprecated and ``nghttp2`` is the +preferred library for incoming DoH support, because ``h2o`` has unfortunately really never been maintained in a way that is suitable for use as a library +(see https://github.com/h2o/h2o/issues/3230). While we took great care to make the migration as painless as possible, ``h2o`` supported HTTP/1 while ``nghttp2`` +does not. This is not an issue for actual DNS over HTTPS clients that support HTTP/2, but might be one in setups running dnsdist behind a reverse-proxy that +does not support HTTP/1, like nginx. We do not plan on implementing HTTP/1, and recommend using HTTP/2 between the reverse-proxy and dnsdist for performance reasons. +For nginx in particular, a possible work-around is to use the `gprc_pass `_ directive as suggested in their `bugtracker `_. + Internal design ^^^^^^^^^^^^^^^ diff --git a/pdns/dnsdistdist/docs/install.rst b/pdns/dnsdistdist/docs/install.rst index 54194b729e..9d24c03dcb 100644 --- a/pdns/dnsdistdist/docs/install.rst +++ b/pdns/dnsdistdist/docs/install.rst @@ -50,7 +50,7 @@ dnsdist depends on the following libraries: * `Editline (libedit) `_ * `libfstrm `_ (optional, dnstap support) * `GnuTLS `_ (optional, DoT and outgoing DoH support) -* `libh2o `_ (optional, incoming DoH support) +* `libh2o `_ (optional, incoming DoH support, deprecated in 1.9.0 in favor of ``nghttp2``) * `libcap `_ (optional, capabilities support) * `libsodium `_ (optional, DNSCrypt and console encryption support) * `LMDB `_ (optional, LMDB support) diff --git a/pdns/dnsdistdist/docs/reference/config.rst b/pdns/dnsdistdist/docs/reference/config.rst index 8dfa212fae..1b17436646 100644 --- a/pdns/dnsdistdist/docs/reference/config.rst +++ b/pdns/dnsdistdist/docs/reference/config.rst @@ -144,7 +144,7 @@ Listen Sockets * ``idleTimeout=30``: int - Set the idle timeout, in seconds. * ``ciphers``: str - The TLS ciphers to use, in OpenSSL format. Ciphers for TLS 1.3 must be specified via ``ciphersTLS13``. * ``ciphersTLS13``: str - The TLS ciphers to use for TLS 1.3, in OpenSSL format. - * ``serverTokens``: str - The content of the Server: HTTP header returned by dnsdist. The default is "h2o/dnsdist". + * ``serverTokens``: str - The content of the Server: HTTP header returned by dnsdist. The default is "h2o/dnsdist" when ``h2o`` is used, "nghttp2-/dnsdist" when ``nghttp2`` is. * ``customResponseHeaders={}``: table - Set custom HTTP header(s) returned by dnsdist. * ``ocspResponses``: list - List of files containing OCSP responses, in the same order than the certificates and keys, that will be used to provide OCSP stapling responses. * ``minTLSVersion``: str - Minimum version of the TLS protocol to support. Possible values are 'tls1.0', 'tls1.1', 'tls1.2' and 'tls1.3'. Default is to require at least TLS 1.0. diff --git a/pdns/dnsdistdist/docs/rules-actions.rst b/pdns/dnsdistdist/docs/rules-actions.rst index 41f531c5e5..2dae142792 100644 --- a/pdns/dnsdistdist/docs/rules-actions.rst +++ b/pdns/dnsdistdist/docs/rules-actions.rst @@ -831,7 +831,8 @@ These ``DNSRule``\ s be one of the following items: sense for DoT or DoH, and for that last one matching on the HTTP Host header using :func:`HTTPHeaderRule` might provide more consistent results. As of the version 2.3.0-beta of h2o, it is unfortunately not possible to extract the SNI value from DoH - connections, and it is therefore necessary to use the HTTP Host header until version 2.3.0 is released. + connections, and it is therefore necessary to use the HTTP Host header until version 2.3.0 is released, + or ``nghttp2`` is used for incoming DoH instead (1.9.0+). :param str name: The exact SNI name to match. diff --git a/pdns/dnsdistdist/docs/upgrade_guide.rst b/pdns/dnsdistdist/docs/upgrade_guide.rst index d089a9d0f7..7f58f3270e 100644 --- a/pdns/dnsdistdist/docs/upgrade_guide.rst +++ b/pdns/dnsdistdist/docs/upgrade_guide.rst @@ -1,6 +1,16 @@ Upgrade Guide ============= +1.8.x to 1.9.0 +-------------- + +dnsdist now supports a new library for dealing with incoming DNS over HTTPS queries: ``nghttp2``. The previously used library, ``h2o``, can still be used +but is now deprecated and will be removed in the future, as it is unfortunately no longer maintained in a way that is suitable for use as a library +(see https://github.com/h2o/h2o/issues/3230). See the ``library`` parameter on the :func:`addDOHLocal` directive for more information on how to select +the library used when dnsdist is built with support for both ``h2o`` and ``nghttp2``. The default is now ``nghttp2`` whenever possible. +Note that ``nghttp2`` only supports HTTP/2, and not HTTP/1, while ``h2o`` supported both. This is not an issue for actual DNS over HTTPS clients that +support HTTP/2, but might be one in setups running dnsdist behind a reverse-proxy that does not support HTTP/1. See :doc:`guides/dns-over-https` for some work-arounds. + 1.7.x to 1.8.0 -------------- -- 2.47.2