From f6b09a2ed646f0a0b54605d4c19a898ab2bbf192 Mon Sep 17 00:00:00 2001

From: Lennart Poettering <lennart@poettering.net>

Date: Mon, 18 Sep 2023 17:51:49 +0200

Subject: [PATCH 2/3] man: document the new

 PollLimitIntervalSec=/PollLimitBurst= settings

(cherry picked from commit 9373fce68de183a615d44fe100dcf22e3c9b8c3e)

---

 man/systemd.socket.xml | 58 ++++++++++++++++++++++++++++++++++--------

 1 file changed, 47 insertions(+), 11 deletions(-)

diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml

index 45555302f1..462978d438 100644

--- a/man/systemd.socket.xml

+++ b/man/systemd.socket.xml

@@ -830,17 +830,53 @@

         <term><varname>TriggerLimitIntervalSec=</varname></term>

         <term><varname>TriggerLimitBurst=</varname></term>

-        <listitem><para>Configures a limit on how often this socket unit may be activated within a specific time

-        interval. The <varname>TriggerLimitIntervalSec=</varname> may be used to configure the length of the time

-        interval in the usual time units <literal>us</literal>, <literal>ms</literal>, <literal>s</literal>,

-        <literal>min</literal>, <literal>h</literal>, … and defaults to 2s (See

-        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details on

-        the various time units understood). The <varname>TriggerLimitBurst=</varname> setting takes a positive integer

-        value and specifies the number of permitted activations per time interval, and defaults to 200 for

-        <varname>Accept=yes</varname> sockets (thus by default permitting 200 activations per 2s), and 20 otherwise (20

-        activations per 2s). Set either to 0 to disable any form of trigger rate limiting. If the limit is hit, the

-        socket unit is placed into a failure mode, and will not be connectible anymore until restarted. Note that this

-        limit is enforced before the service activation is enqueued.</para></listitem>

+        <listitem><para>Configures a limit on how often this socket unit may be activated within a specific

+        time interval. The <varname>TriggerLimitIntervalSec=</varname> setting may be used to configure the

+        length of the time interval in the usual time units <literal>us</literal>, <literal>ms</literal>,

+        <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, … and defaults to 2s (See

+        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for

+        details on the various time units understood). The <varname>TriggerLimitBurst=</varname> setting

+        takes a positive integer value and specifies the number of permitted activations per time interval,

+        and defaults to 200 for <varname>Accept=yes</varname> sockets (thus by default permitting 200

+        activations per 2s), and 20 otherwise (20 activations per 2s). Set either to 0 to disable any form of

+        trigger rate limiting.</para>

+

+        <para>If the limit is hit, the socket unit is placed into a failure mode, and will not be connectible

+        anymore until restarted. Note that this limit is enforced before the service activation is

+        enqueued.</para>

+

+        <para>Compare with <varname>PollLimitIntervalSec=</varname>/<varname>PollLimitBurst=</varname>

+        described below, which implements a temporary slowdown if a socket unit is flooded with incoming

+        traffic, as opposed to the permanent failure state

+        <varname>TriggerLimitIntervalSec=</varname>/<varname>TriggerLimitBurst=</varname> results in.</para>

+        </listitem>

+      </varlistentry>

+

+      <varlistentry>

+        <term><varname>PollLimitIntervalSec=</varname></term>

+        <term><varname>PollLimitBurst=</varname></term>

+

+        <listitem><para>Configures a limit on how often polling events on the file descriptors backing this

+        socket unit will be considered. This pair of settings is similar to

+        <varname>TriggerLimitIntervalSec=</varname>/<varname>TriggerLimitBurst=</varname> but instead of

+        putting a (fatal) limit on the activation frequency puts a (transient) limit on the polling

+        frequency. The expected parameter syntax and range are identical to that of the aforementioned

+        options, and can be disabled the same way.</para>

+

+        <para>If the polling limit is hit polling is temporarily disabled on it until the specified time

+        window passes. The polling limit hence slows down connection attempts if hit, but unlike the trigger

+        limit won't cause permanent failures. It's the recommended mechanism to deal with DoS attempts

+        through packet flooding.</para>

+

+        <para>The polling limit is enforced per file descriptor to listen on, as opposed to the trigger limit

+        which is enforced for the entire socket unit. This distinction matters for socket units that listen

+        on multiple file descriptors (i.e. have multiple <varname>ListenXYZ=</varname> stanzas).</para>

+

+        <para>These setting defaults to 150 (in case of <varname>Accept=yes</varname>) and 15 (otherwise)

+        polling events per 2s. This is considerably lower than the default values for the trigger limit (see

+        above) and means that the polling limit should typically ensure the trigger limit is never hit,

+        unless one of them is reconfigured or disabled.</para>

+        </listitem>

       </varlistentry>

     </variablelist>