From: Remi Gacogne Date: Fri, 20 Oct 2023 07:14:39 +0000 (+0200) Subject: dnsdist: Fix documentation issues reported by Peter (thanks!) X-Git-Tag: rec-5.0.0-beta1~15^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5ff7f546ee339a07e38cf53ca7fdea3ff55c85b5;p=thirdparty%2Fpdns.git dnsdist: Fix documentation issues reported by Peter (thanks!) --- diff --git a/pdns/dnsdistdist/docs/advanced/tls-sessions-management.rst b/pdns/dnsdistdist/docs/advanced/tls-sessions-management.rst index c0855930dc..8b6b5e61cc 100644 --- a/pdns/dnsdistdist/docs/advanced/tls-sessions-management.rst +++ b/pdns/dnsdistdist/docs/advanced/tls-sessions-management.rst @@ -30,13 +30,13 @@ dnsdist supports both server's side (sessions) and client's side (tickets) resum Since server-side sessions cannot be shared between several instances, and pretty much all clients support tickets anyway, we do recommend disabling the sessions by passing ``numberOfStoredSessions=0`` to the :func:`addDOHLocal` (for DNS over HTTPS) and :func:`addTLSLocal` (for DNS over TLS) functions. -By default, dnsdist will generate a new, random STEK at startup for each `addTLSLocal` and `addDOHLocal` directives, and rotate these STEKs every 12 hours. For each frontend it will keep 5 keys in memory, with only the last one marked as active and used to encrypt new tickets while the remaining ones can still be used to decrypt existing tickets after a rotation. The rotation time and the number of keys to keep in memory can be configured via the ``numberOfTicketsKeys`` and ``ticketsKeysRotationDelay`` parameters of the :func:`addDOHLocal` (for DNS over HTTPS) and :func:`addTLSLocal` (for DNS over TLS) functions. -When the automatic rotation mechanism kicks in a new, random key will be added to the list of keys. With the OpenSSL provider, the new key become active, so new tickets will be encrypted with this key, and the existing keys become passive and only be used to decrypt existing tickets. With the GnuTLS provider only one key is currently supported so the existing keys are immediately discarded. +By default, dnsdist will generate a new, random STEK at startup for each :func:`addTLSLocal` and :func:`addDOHLocal` directive, and rotate these STEKs every 12 hours. For each frontend it will keep 5 keys in memory, with only the last one marked as active and used to encrypt new tickets while the remaining ones can still be used to decrypt existing tickets after a rotation. The rotation time and the number of keys to keep in memory can be configured via the ``numberOfTicketsKeys`` and ``ticketsKeysRotationDelay`` parameters of the :func:`addDOHLocal` (for DNS over HTTPS) and :func:`addTLSLocal` (for DNS over TLS) functions. +When the automatic rotation mechanism kicks in a new, random key will be added to the list of keys. With the OpenSSL provider, the new key becomes active, so new tickets will be encrypted with this key, and the existing keys become passive and only be used to decrypt existing tickets. With the GnuTLS provider only one key is currently supported so the existing keys are immediately discarded. This automatic rotation can be disabled by setting ``ticketsKeysRotationDelay`` to 0. It is also possible to manually request a STEK rotation using the :func:`getDOHFrontend` (DoH) and :func:`getTLSContext` (DoT) functions to retrieve the bind object, and calling its ``rotateTicketsKey`` method (:meth:`DOHFrontend:rotateTicketsKey`, :meth:`TLSContext:rotateTicketsKey`). -The default settings should be fine for most deployments, but generating a random key for every dnsdist instance will not allow resuming the session from a different instance in a cluster. It is also not very useful to have a different key for every ``addTLSLocal`` and ``addDOHLocal`` directives if you are using the same certificate and key, and it would be much better to use the same STEK to improve the session resumption ratio. +The default settings should be fine for most deployments, but generating a random key for every dnsdist instance will not allow resuming the session from a different instance in a cluster. It is also not very useful to have a different key for every :func:`addTLSLocal` and :func:`addDOHLocal` directive if you are using the same certificate and key, and it would be much better to use the same STEK to improve the session resumption ratio. In that case it is possible to generate the STEK outside of dnsdist, write it to a file, distribute it to all instances using something like rsync over SSH, and load that file from dnsdist. Please remember that the STEK contains very sensitive data, and should be well-protected from access by unauthorized users. It means that special care should be taken to setting the right permissions on that file. Automatic rotation should then be disabled by setting ``ticketsKeysRotationDelay`` to 0. diff --git a/pdns/dnsdistdist/docs/advanced/tuning.rst b/pdns/dnsdistdist/docs/advanced/tuning.rst index 6e7eb625a1..c8d78a0d67 100644 --- a/pdns/dnsdistdist/docs/advanced/tuning.rst +++ b/pdns/dnsdistdist/docs/advanced/tuning.rst @@ -119,7 +119,7 @@ Incoming and outgoing DNS over TLS, as well as outgoing DNS over HTTPS, might be TLS performance --------------- -For DNS over HTTPS and DNS over TLS, in addition to the advices above we advise reading the :doc:`tls-sessions-management` page to know how to improve TLS session resumption ratio, which has a huge impact on CPU usage and latency. +For DNS over HTTPS and DNS over TLS, in addition to the advice above we suggest reading the :doc:`tls-sessions-management` page to learn how to improve TLS session resumption ratio, which has a huge impact on CPU usage and latency. Rules and Lua -------------