From: Remi Gacogne Date: Thu, 16 May 2024 08:48:23 +0000 (+0200) Subject: dnsdist: Document the new tag action options for dynamic rules X-Git-Tag: rec-5.1.0-beta1~27^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9a52aa3cb5ed88e13577068e999d5e873f1ef051;p=thirdparty%2Fpdns.git dnsdist: Document the new tag action options for dynamic rules --- diff --git a/pdns/dnsdistdist/docs/reference/config.rst b/pdns/dnsdistdist/docs/reference/config.rst index 0484a2e09a..5fd3096281 100644 --- a/pdns/dnsdistdist/docs/reference/config.rst +++ b/pdns/dnsdistdist/docs/reference/config.rst @@ -1669,10 +1669,13 @@ faster than the existing rules. Represents a group of dynamic block rules. - .. method:: DynBlockRulesGroup:setCacheMissRatio(ratio, seconds, reason, blockingTime, minimumNumberOfResponses, minimumGlobalCacheHitRatio, [, action [, warningRate]]) + .. method:: DynBlockRulesGroup:setCacheMissRatio(ratio, seconds, reason, blockingTime, minimumNumberOfResponses, minimumGlobalCacheHitRatio, [, action [, warningRate, [options]]]) .. versionadded:: 1.9.0 + .. versionadded:: 2.0.0 + ``options`` optional parameter added + Adds a rate-limiting rule for the ratio of cache-misses responses over the total number of responses for a given client. A minimum global cache-hit ratio has to specified to prevent false-positive when the cache is empty. @@ -1684,6 +1687,12 @@ faster than the existing rules. :param float minimumGlobalCacheHitRatio: The minimum global cache-hit ratio (over all pools, so ``cache-hits / (cache-hits + cache-misses)``) for that rule to be applied. :param int action: The action to take when the dynamic block matches, see :ref:`DNSAction `. (default to the one set with :func:`setDynBlocksAction`) :param float warningRatio: If set to a non-zero value, the ratio above which a warning message will be issued and a no-op block inserted + :param table options: A table with key: value pairs, see below for supported values. + + Options: + + * ``tagKey``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set + * ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set .. method:: DynBlockRulesGroup:setMasks(v4, v6, port) @@ -1700,7 +1709,10 @@ faster than the existing rules. :param int v6: Number of bits to keep for IPv6 addresses. Default is 128 :param int port: Number of bits of port to consider over IPv4. Default is 0 meaning that the port is not taken into account - .. method:: DynBlockRulesGroup:setQueryRate(rate, seconds, reason, blockingTime [, action [, warningRate]]) + .. method:: DynBlockRulesGroup:setQueryRate(rate, seconds, reason, blockingTime [, action [, warningRate, [options]]]) + + .. versionadded:: 2.0.0 + ``options`` optional parameter added Adds a query rate-limiting rule, equivalent to: ``` @@ -1713,6 +1725,12 @@ faster than the existing rules. :param int blockingTime: The number of seconds this block to expire :param int action: The action to take when the dynamic block matches, see :ref:`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 + :param table options: A table with key: value pairs, see below for supported values. + + Options: + + * ``tagKey``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set + * ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set .. method:: DynBlockRulesGroup:setNewBlockInsertedHook(hook) @@ -1727,7 +1745,10 @@ faster than the existing rules. * the duration of the block in seconds * whether this is a warning block (true) or not (false) - .. method:: DynBlockRulesGroup:setRCodeRate(rcode, rate, seconds, reason, blockingTime [, action [, warningRate]]) + .. method:: DynBlockRulesGroup:setRCodeRate(rcode, rate, seconds, reason, blockingTime [, action [, warningRate, [options]]]) + + .. versionadded:: 2.0.0 + ``options`` optional parameter added .. note:: Cache hits are inserted into the in-memory ring buffers since 1.8.0, so they are now considered when computing the rcode rate. @@ -1744,11 +1765,20 @@ faster than the existing rules. :param int blockingTime: The number of seconds this block to expire :param int action: The action to take when the dynamic block matches, see :ref:`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 + :param table options: A table with key: value pairs, see below for supported values. + + Options: + + * ``tagKey``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set + * ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set - .. method:: DynBlockRulesGroup:setRCodeRatio(rcode, ratio, seconds, reason, blockingTime, minimumNumberOfResponses [, action [, warningRate]]) + .. method:: DynBlockRulesGroup:setRCodeRatio(rcode, ratio, seconds, reason, blockingTime, minimumNumberOfResponses [, action [, warningRate, [options]]]) .. versionadded:: 1.5.0 + .. versionadded:: 2.0.0 + ``options`` optional parameter added + .. note:: Cache hits are inserted into the in-memory ring buffers since 1.8.0, so they are now considered when computing the rcode ratio. @@ -1762,8 +1792,17 @@ faster than the existing rules. :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:`DNSAction `. (default to the one set with :func:`setDynBlocksAction`) :param float warningRatio: If set to a non-zero value, the ratio above which a warning message will be issued and a no-op block inserted + :param table options: A table with key: value pairs, see below for supported values. + + Options: + + * ``tagKey``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set + * ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set - .. method:: DynBlockRulesGroup:setQTypeRate(qtype, rate, seconds, reason, blockingTime [, action [, warningRate]]) + .. method:: DynBlockRulesGroup:setQTypeRate(qtype, rate, seconds, reason, blockingTime [, action [, warningRate, [options]]]) + + .. versionadded:: 2.0.0 + ``options`` optional parameter added Adds a rate-limiting rule for queries of type ``qtype``, equivalent to: ``` @@ -1777,8 +1816,17 @@ faster than the existing rules. :param int blockingTime: The number of seconds this block to expire :param int action: The action to take when the dynamic block matches, see :ref:`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 + :param table options: A table with key: value pairs, see below for supported values. + + Options: + + * ``tagKey``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set + * ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set - .. method:: DynBlockRulesGroup:setResponseByteRate(rate, seconds, reason, blockingTime [, action [, warningRate]]) + .. method:: DynBlockRulesGroup:setResponseByteRate(rate, seconds, reason, blockingTime [, action [, warningRate, [options]]]) + + .. versionadded:: 2.0.0 + ``options`` optional parameter added .. note:: Cache hits are inserted into the in-memory ring buffers since 1.8.0, so they are now considered when computing the bandwidth rate. @@ -1794,8 +1842,14 @@ faster than the existing rules. :param int blockingTime: The number of seconds this block to expire :param int action: The action to take when the dynamic block matches, see :ref:`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 + :param table options: A table with key: value pairs, see below for supported values. + + Options: + + * ``tagKey``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set + * ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set - .. method:: DynBlockRulesGroup:setSuffixMatchRule(seconds, reason, blockingTime, action , visitor) + .. method:: DynBlockRulesGroup:setSuffixMatchRule(seconds, reason, blockingTime, action, visitor, [options]) .. versionadded:: 1.4.0 @@ -1805,6 +1859,9 @@ faster than the existing rules. .. versionchanged:: 1.9.0 This visitor function can now optionally return an additional integer which will be set as the ``action`` for the dynamic block. + .. versionadded:: 2.0.0 + ``options`` optional parameter added + Set a Lua visitor function that will be called for each label of every domain seen in queries and responses. The function receives a :class:`StatNode` object representing the stats of the parent, a :class:`StatNodeStats` one with the stats of the current label and a second :class:`StatNodeStats` with the stats of the current node plus all its children. Note that this function will not be called if a FFI version has been set using :meth:`DynBlockRulesGroup:setSuffixMatchRuleFFI` If the function returns ``true``, the current suffix will be added to the block list, meaning that the exact name and all its sub-domains will be blocked according to the `seconds`, `reason`, `blockingTime` and `action` parameters. Since 1.7.0, the function can return an additional string, in addition to the boolean, which will be set as the ``reason`` for the dynamic block. @@ -1817,11 +1874,20 @@ faster than the existing rules. :param int blockingTime: The number of seconds this block to expire :param int action: The action to take when the dynamic block matches, see :ref:`DNSAction `. (default to the one set with :func:`setDynBlocksAction`) :param function visitor: The Lua function to call. + :param table options: A table with key: value pairs, see below for supported values. + + Options: + + * ``tagKey``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set + * ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set - .. method:: DynBlockRulesGroup:setSuffixMatchRuleFFI(seconds, reason, blockingTime, action , visitor) + .. method:: DynBlockRulesGroup:setSuffixMatchRuleFFI(seconds, reason, blockingTime, action , visitor, [options]) .. versionadded:: 1.4.0 + .. versionadded:: 2.0.0 + ``options`` optional parameter added + Set a Lua FFI visitor function that will be called for each label of every domain seen in queries and responses. The function receives a `dnsdist_ffi_stat_node_t` object containing the stats of the parent, a second one with the stats of the current label and one with the stats of the current node plus all its children. If the function returns ``true``, the current suffix will be added to the block list, meaning that the exact name and all its sub-domains will be blocked according to the `seconds`, `reason`, `blockingTime` and `action` parameters. Selected domains can be excluded from this processing using the :meth:`DynBlockRulesGroup:excludeDomains` method. @@ -1831,6 +1897,12 @@ faster than the existing rules. :param int blockingTime: The number of seconds this block to expire :param int action: The action to take when the dynamic block matches, see :ref:`DNSAction `. (default to the one set with :func:`setDynBlocksAction`) :param function visitor: The Lua FFI function to call. + :param table options: A table with key: value pairs, see below for supported values. + + Options: + + * ``tagKey``: str - If ``action`` is set to ``DNSAction.SetTag``, the name of the tag that will be set + * ``tagValue``: str - If ``action`` is set to ``DNSAction.SetTag``, the value of the tag that will be set .. method:: DynBlockRulesGroup:apply()