man: improve documentation for RestartSteps (#40879)

I found the existing explanation of RestartSteps to be simply
impenetrable. Even providing the full docs context to several of our new
AI overlords resulted in wildly different (and completely incorrect)
explanations of the final restart intervals.

Digging through the code, I found the restart delay computation in
`service_restart_usec_next` in `src/core/service.c`.

I've updated the documentation for RestartSteps with an example,
suggested value range and a detailed enough explanation that accurately
describes the current behavior.

(cherry picked from commit 4724cf5526b5c6a08267d1b1bb23e962ebe60521)
(cherry picked from commit 7b1ea2374aa9834e41d4e444f54e25cc5bd7f7b9)
(cherry picked from commit 4479c8a0fa937f5e7dc0f519f5b184e3ad86f11a)

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index f6d535bda42d8fe5d9da07c92bb732330531f00e..bfa235796548519b7ad6d7491cc76b91438d1628 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -581,7 +581,29 @@
         <term><varname>RestartSteps=</varname></term>
         <listitem><para>Configures the number of exponential steps to take to increase the interval
         of auto-restarts from <varname>RestartSec=</varname> to <varname>RestartMaxDelaySec=</varname>.
-        Takes a positive integer or 0 to disable it. Defaults to 0.</para>
+        Takes a positive integer or 0 to disable it. Defaults to 0. <emphasis>Hint:</emphasis> values
+        between 3 and 5 are good choices when exponential backoff is desired.</para>
+
+        <para>Example:</para>
+
+        <programlisting>RestartSec=10s
+RestartSteps=4
+RestartMaxDelaySec=160s</programlisting>
+
+        <para>This will produce the following restart intervals: 10s, 20s, 40s, 80s, 160s, 160s, 160s, etc.
+        Notice the geometric interpolation and the resulting constant ratio between intervals; here it is 2.
+        The formula for the <emphasis>ratio</emphasis> is
+        <inlineequation>
+          <mathphrase>
+            (<varname>RestartMaxDelaySec</varname> / <varname>RestartSec</varname>)^(1 / <varname>RestartSteps</varname>)
+          </mathphrase>
+        </inlineequation>. A (repeating) delay equal to <varname>RestartMaxDelaySec=</varname> is always
+        reached after
+        <inlineequation>
+          <mathphrase>
+            <varname>RestartSteps</varname> + 1
+          </mathphrase>
+        </inlineequation> steps.</para>
 
         <para>This setting is effective only if <varname>RestartMaxDelaySec=</varname> is also set and
         <varname>RestartSec=</varname> is not zero.</para>