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>