dnsdist: Implement Cache-Control headers in DoH

[thirdparty/pdns.git] / pdns / dnsdistdist / docs / reference / config.rst

diff --git a/pdns/dnsdistdist/docs/reference/config.rst b/pdns/dnsdistdist/docs/reference/config.rst
index 7d40c1b552e876655440dda7411fe1e9c59ff849..1ea9c843fb50784a14c8188a5e3298b658958394 100644 (file)
--- a/pdns/dnsdistdist/docs/reference/config.rst
+++ b/pdns/dnsdistdist/docs/reference/config.rst
@@ -107,6 +107,9 @@ Listen Sockets
 
   .. versionadded:: 1.4.0
 
+  .. versionchanged:: 1.5.0
+    ``sendCacheControlHeaders`` option added.
+
   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.
 
@@ -137,6 +140,7 @@ Listen Sockets
   * ``numberOfStoredSessions``: int - The maximum number of sessions kept in memory at the same time. Default is 20480. Setting this value to 0 disables stored session entirely.
   * ``preferServerCiphers``: bool - Whether to prefer the order of ciphers set by the server instead of the one set by the client. Default is true, meaning that the order of the server is used.
   * ``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.
+  * ``sendCacheControlHeaders``: bool - Whether to parse the response to find the lowest TTL and set a HTTP Cache-Control header accordingly. Default is true.
 
 .. function:: addTLSLocal(address, certFile(s), keyFile(s) [, options])
 
@@ -227,6 +231,12 @@ Control Socket, Console and Webserver
 
   Returns true while the console client is parsing the configuration.
 
+.. function:: inConfigCheck()
+
+  .. versionadded:: 1.5.0
+
+  Returns true while the configuration is being checked, ie when run with ``--check-config``.
+
 .. function:: makeKey()
 
   Generate and print an encryption key.
@@ -428,9 +438,12 @@ Servers
 
 .. function:: getServer(index) -> Server
 
+  .. versionchanged:: 1.5.0
+    ``index`` might be an UUID.
+
   Get a :class:`Server`
 
-  :param int index: The number of the server (as seen in :func:`showServers`).
+  :param int or str index: The number of the server (as seen in :func:`showServers`) or its UUID as a string.
   :returns:  The :class:`Server` object or nil
 
 .. function:: getServers()
@@ -438,11 +451,15 @@ Servers
   Returns a table with all defined servers.
 
 .. function:: rmServer(index)
+              rmServer(uuid)
               rmServer(server)
 
+  .. versionchanged:: 1.5.0
+    ``uuid`` selection added.
+
   Remove a backend server.
 
-  :param int index: The number of the server (as seen in :func:`showServers`).
+  :param int or str index: The number of the server (as seen in :func:`showServers`), its UUID as a string, or a server object.
   :param Server server: A :class:`Server` object as returned by e.g. :func:`getServer`.
 
 Server Functions
@@ -1020,6 +1037,21 @@ faster than the existing rules.
     :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
     :param int warningRate: If set to a non-zero value, the rate above which a warning message will be issued and a no-op block inserted
 
+  .. method:: DynBlockRulesGroup:setRCodeRatio(rcode, ratio, seconds, reason, blockingTime, minimumNumberOfResponses [, action [, warningRate]])
+
+    .. versionadded:: 1.5.0
+
+    Adds a rate-limiting rule for the ratio of responses of code ``rcode`` over the total number of responses for a given client.
+
+    :param int rcode: The response code
+    :param int ratio: Ratio of responses per second of the given rcode over the total number of responses for this client to exceed
+    :param int seconds: Number of seconds the ratio has been exceeded
+    :param string reason: The message to show next to the blocks
+    :param int blockingTime: The number of seconds this block to expire
+    :param int minimumNumberOfResponses: How many total responses is required for this rule to apply
+    :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
+    :param int warningRatio: If set to a non-zero value, the ratio above which a warning message will be issued and a no-op block inserted
+
   .. method:: DynBlockRulesGroup:setQTypeRate(qtype, rate, seconds, reason, blockingTime [, action [, warningRate]])
 
     .. versionchanged:: 1.3.3