From 0426584a92a8996213106ad1374b7a531fa68e36 Mon Sep 17 00:00:00 2001 From: Remi Gacogne Date: Thu, 30 Jul 2020 17:23:59 +0200 Subject: [PATCH] dnsdist: Better documentation for HTTP responses map Including the fact that in 1.5.0 the paths should be listed in the list of path passed to `addDOHLocal` to be able to match a response rule. --- pdns/dnsdistdist/docs/guides/dns-over-https.rst | 16 ++++++++++------ pdns/dnsdistdist/docs/reference/config.rst | 4 ++-- pdns/dnsdistdist/docs/upgrade_guide.rst | 9 ++++++++- 3 files changed, 20 insertions(+), 9 deletions(-) diff --git a/pdns/dnsdistdist/docs/guides/dns-over-https.rst b/pdns/dnsdistdist/docs/guides/dns-over-https.rst index 339e3563ba..ab0c23fdac 100644 --- a/pdns/dnsdistdist/docs/guides/dns-over-https.rst +++ b/pdns/dnsdistdist/docs/guides/dns-over-https.rst @@ -17,13 +17,10 @@ In order to support multiple certificates and keys, for example an ECDSA and an The certificate chain presented by the server to an incoming client will then be selected based on the algorithms this client advertised support for. -A fourth parameter may be added to specify the URL path(s) used by -DoH. If you want your DoH server to handle -``https://example.com/dns-query``, you have to add ``"/dns-query"`` to -the call to :func:`addDOHLocal`. It is optional and defaults to ``/``, the root of your HTTP site. +A fourth parameter may be added to specify the URL path(s) used by DoH. If you want your DoH server to handle ``https://example.com/dns-query-endpoint``, you have to add ``"/dns-query-endpoint"`` to +the call to :func:`addDOHLocal`. It is optional and defaults to ``/`` in 1.4.0, and ``/dns-query`` since 1.5.0. -The fifth parameter, if present, indicates various options. For -instance, you use it to indicate custom HTTP headers. An example is:: +The fifth parameter, if present, indicates various options. For instance, you use it to indicate custom HTTP headers. An example is:: addDOHLocal('2001:db8:1:f00::1', '/etc/ssl/certs/example.com.pem', '/etc/ssl/private/example.com.key', "/dns", {customResponseHeaders={["x-foo"]="bar"}} @@ -31,6 +28,13 @@ A more complicated (and more realistic) example is when you want to indicate met addDOHLocal('2001:db8:1:f00::1', '/etc/ssl/certs/example.com.pem', '/etc/ssl/private/example.com.key', "/", {customResponseHeaders={["link"]=" rel=\\"service-meta\\"; type=\\"text/html\\""}}) +It is also possible to set HTTP response rules to intercept HTTP queries early, before the DNS payload, if any, has been processed, to send custom responses including error pages, redirects or even serve static content. First a rule needs to be defined using :func:`newDOHResponseMapEntry`, then a set of rules can be applied to a DoH frontend via :meth:`DOHFrontend.setResponsesMap`. +For example, to send an HTTP redirect to queries asking for ``/rfc``, the following configuration can be used: + + map = { newDOHResponseMapEntry("^/rfc$", 307, "https://www.rfc-editor.org/info/rfc8484") } + dohFE = getDOHFrontend(0) + dohFE:setResponsesMap(map) + In case you want to run DNS-over-HTTPS behind a reverse proxy you probably don't want to encrypt your traffic between reverse proxy and dnsdist. To let dnsdist listen for DoH queries over HTTP on localhost at port 8053 add one of the following to your config:: diff --git a/pdns/dnsdistdist/docs/reference/config.rst b/pdns/dnsdistdist/docs/reference/config.rst index a56a6d8647..ee4629de6a 100644 --- a/pdns/dnsdistdist/docs/reference/config.rst +++ b/pdns/dnsdistdist/docs/reference/config.rst @@ -123,7 +123,7 @@ Listen Sockets The default port is 443. :param str certFile(s): The path to a X.509 certificate file in PEM format, or a list of paths to such files. :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. - :param str-or-list urls: A base URL, or a list of base URLs, to accept queries on. Any query with a path under one of these will be treated as a DoH query. The default is /dns-query. + :param str-or-list urls: The path part of a URL, or a list of paths, to accept queries on. Any query with a path under one of these will be treated as a DoH query. The default is /dns-query. :param table options: A table with key: value pairs with listen options. Options: @@ -1372,7 +1372,7 @@ DOHFrontend .. versionadded:: 1.4.0 - Return a DOHResponseMapEntry that can be used with :meth:`DOHFrontend.setResponsesMap`. Every query whose path matches the regular expression supplied in ``regex`` will be immediately answered with a HTTP response. + Return a DOHResponseMapEntry that can be used with :meth:`DOHFrontend.setResponsesMap`. Every query whose path is listed in the ``urls`` parameter to :func:`addDOHLocal` and matches the regular expression supplied in ``regex`` will be immediately answered with a HTTP response. The status of the HTTP response will be the one supplied by ``status``, and the content set to the one supplied by ``content``, except if the status is a redirection (3xx) in which case the content is expected to be the URL to redirect to. :param str regex: A regular expression to match the path against. diff --git a/pdns/dnsdistdist/docs/upgrade_guide.rst b/pdns/dnsdistdist/docs/upgrade_guide.rst index 21cc34f779..27be26a2d0 100644 --- a/pdns/dnsdistdist/docs/upgrade_guide.rst +++ b/pdns/dnsdistdist/docs/upgrade_guide.rst @@ -4,8 +4,15 @@ Upgrade Guide 1.4.0 to 1.5.x -------------- -DOH endpoints specified in the fourth parameter of :func:`addDOHLocal` are now specified as exact URLs instead of path prefixes. The default endpoint also switched from ``/`` to ``/dns-query``. +DOH endpoints specified in the fourth parameter of :func:`addDOHLocal` are now specified as exact paths instead of path prefixes. The default endpoint also switched from ``/`` to ``/dns-query``. For example, ``addDOHLocal('2001:db8:1:f00::1', '/etc/ssl/certs/example.com.pem', '/etc/ssl/private/example.com.key', { "/dns-query" })`` will now only accept queries for ``/dns-query`` and no longer for ``/dns-query/foo/bar``. +This change also impacts the HTTP response rules set via :meth:`DOHFrontend.setResponsesMap`, since queries whose paths are not allowed will be discarded before the rules are evaluated. +If you want to accept DoH queries on ``/dns-query`` and redirect ``/rfc`` to the DoH RFC, you need to list ``/rfc`` in the list of paths: + + addDOHLocal('2001:db8:1:f00::1', '/etc/ssl/certs/example.com.pem', '/etc/ssl/private/example.com.key', { '/dns-query', '/rfc'}) + map = { newDOHResponseMapEntry("^/rfc$", 307, "https://www.rfc-editor.org/info/rfc8484") } + dohFE = getDOHFrontend(0) + dohFE:setResponsesMap(map) The systemd service-file that is installed no longer uses the ``root`` user to start. It uses the user and group set with the ``--with-service-user`` and ``--with-service-group`` switches during configuration, "dnsdist" by default. -- 2.47.2