From 4724cf5526b5c6a08267d1b1bb23e962ebe60521 Mon Sep 17 00:00:00 2001
From: Val Markovic <val@markovic.io>
Date: Mon, 2 Mar 2026 04:38:35 +0100
Subject: [PATCH] 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.
---
 man/systemd.service.xml | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 8b9994a46a..549f36af1d 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -590,7 +590,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>