SymbX/systemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

man: improve documentation for RestartSteps (#40879)

Browse Source 
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.
This commit is contained in:
Val Markovic
2026-03-02 12:38:35 +09:00
committed by GitHub
parent 9d3b73d9bf
commit 4724cf5526
1 changed files with 23 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
man/systemd.service.xml
+23 -1
View File
@@ -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>