From ab5fa6f2718ba27896ab6c6b37fce4cb4a39b8ff Mon Sep 17 00:00:00 2001 From: Mo Chen Date: Thu, 6 Aug 2026 11:14:50 -0500 Subject: [PATCH 1/3] doc: rate_limit uses max_age, not max-age The YAML parser reads max_age with an underscore, in three places: the queue node (limiter.h), the ip-rep node and its perma-block sub-node (ip_reputation.cc). Every mention in the documentation spelled it max-age, including the three worked examples, so a configuration copied from the docs left all three at their default of 0 and silently disabled queue expiry and both IP-reputation aging paths. The --maxage pparam description also referred to a "max-age" that matches neither the option nor the key, so it now just says maximum age. --- doc/admin-guide/plugins/rate_limit.en.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/admin-guide/plugins/rate_limit.en.rst b/doc/admin-guide/plugins/rate_limit.en.rst index 7f3d5ccf1aa..7d80259084c 100644 --- a/doc/admin-guide/plugins/rate_limit.en.rst +++ b/doc/admin-guide/plugins/rate_limit.en.rst @@ -92,7 +92,7 @@ are available: .. option:: --maxage - An optional ``max-age`` for how long a transaction can sit in the delay queue. + An optional maximum age for how long a transaction can sit in the delay queue. The value (default 0) is the age in seconds. .. option:: --prefix @@ -149,7 +149,7 @@ and nodes are documented below. rate: 200 queue: size: 1000 - max-age: 30 + max_age: 30 metrics: tag: example.com prefix: ddos @@ -163,11 +163,11 @@ and nodes are documented below. buckets: 10 size: 15 percentage: 90 - max-age: 300 + max_age: 300 perma-block: limit: 100 threshold: 1 - max-age: 1800 + max_age: 1800 lists: - name: internal cidr: @@ -212,8 +212,8 @@ For the top level `selector` node, the following options are available: how many queued transactions we will allow. When this threshold is reached, all additional connections are immediately errored out in the TLS handshake. - The queue option can include a `size` and a `max-age` option. The size is - default to ``UINT_MAX``, which is essentially unlimited. The max-age is + The queue option can include a `size` and a `max_age` option. The size is + default to ``UINT_MAX``, which is essentially unlimited. The max_age is default to ``0``, which means no age limit. No queue is enabled without this configuration directive, but it can also be @@ -268,7 +268,7 @@ and the following options: This is the minimum percentage of the ``limit`` that the pressure must be at, before we start blocking IPs. The default is ``0.9`` which means ``90%`` of the limit. -.. option:: max-age +.. option:: max_age This is used for aging out entries out of the LRU, the default is ``0`` which means no aging happens. Even with no aging, entries will eventually fall out of buckets @@ -289,7 +289,7 @@ blocked for a long time. The configuration for this bucket is: This option specifies from which bucket an IP is allowed to move from into the perma block bucket. A good value here is likely ``0`` or ``1``, which is very conservative. -.. option:: max-age +.. option:: max_age Like above, but only applies to the long term (`perma-block`) bucket. Default is ``0``, which means no aging to this bucket is applied. From de95440323736da84ffbdc2deef23cdc395fed1e Mon Sep 17 00:00:00 2001 From: Mo Chen Date: Fri, 7 Aug 2026 10:08:52 -0500 Subject: [PATCH 2/3] Update rate limit documentation for max-age option Clarify documentation regarding the 'max-age' option and its behavior in previous versions. --- doc/admin-guide/plugins/rate_limit.en.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/admin-guide/plugins/rate_limit.en.rst b/doc/admin-guide/plugins/rate_limit.en.rst index 7d80259084c..cb504702871 100644 --- a/doc/admin-guide/plugins/rate_limit.en.rst +++ b/doc/admin-guide/plugins/rate_limit.en.rst @@ -275,6 +275,11 @@ and the following options: because of the LRU mechanism that kicks in. The aging is here to make sure a spike in traffic from an IP doesn't keep the entry for too long in the LRUs. + Note that this option was incorrectly documented as ``max-age`` with a hyphen in previous + versions. The code ignores ``max-age`` in all versions of this plugin. We have chosen + to keep the behavior the same and update the documentation, so that previously inert + configurations don't activate unexpectedly with an upgrade. + In addition, there's an optional configuration for the permanently blocking buckets, `perma-block`. This is a special bucket, which is only used for IPs which have been blocked for a long time. The configuration for this bucket is: From ce75987c094e260be598b0343360d606416df06e Mon Sep 17 00:00:00 2001 From: Mo Chen Date: Fri, 7 Aug 2026 11:02:27 -0500 Subject: [PATCH 3/3] doc: rate_limit --maxage is milliseconds, queue max_age is seconds The pparam path stores --maxage as std::chrono::milliseconds (txn_limiter.cc), while the YAML path stores max_age as std::chrono::seconds (limiter.h). The documentation described both as seconds, so a --maxage value was off by a factor of 1000. Document the units as they behave and note the discrepancy, rather than changing the expiry of existing configurations. Also state the unit on the YAML side, which was unstated, and fix the "is default to" wording. --- doc/admin-guide/plugins/rate_limit.en.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/doc/admin-guide/plugins/rate_limit.en.rst b/doc/admin-guide/plugins/rate_limit.en.rst index cb504702871..15b0e6c591d 100644 --- a/doc/admin-guide/plugins/rate_limit.en.rst +++ b/doc/admin-guide/plugins/rate_limit.en.rst @@ -93,7 +93,12 @@ are available: .. option:: --maxage An optional maximum age for how long a transaction can sit in the delay queue. - The value (default 0) is the age in seconds. + The value (default 0) is the age in **milliseconds**. + + Note that the equivalent YAML setting, ``max_age`` under a ``queue`` node, is in + seconds. The two configuration paths have always differed by a factor of 1000, so + the units are documented here as they behave rather than made consistent, to avoid + changing the expiry of existing configurations. .. option:: --prefix @@ -212,9 +217,9 @@ For the top level `selector` node, the following options are available: how many queued transactions we will allow. When this threshold is reached, all additional connections are immediately errored out in the TLS handshake. - The queue option can include a `size` and a `max_age` option. The size is - default to ``UINT_MAX``, which is essentially unlimited. The max_age is - default to ``0``, which means no age limit. + The queue option can include a `size` and a `max_age` option. The size defaults + to ``UINT_MAX``, which is essentially unlimited. The max_age is in seconds and + defaults to ``0``, which means no age limit. No queue is enabled without this configuration directive, but it can also be disabled explicitly if the size is set to ``0``.