From ca50a3cd2f422972b2d4cf1ce3620e02579c76fa Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Thu, 29 Oct 2026 08:54:08 +0100 Subject: [PATCH] man: document total delay of exponential restart backoff The RestartSteps= documentation explains the ratio between two restart delays. It doesn't say how long the service manager keeps restarting a failing service, and that's what an operator usually wants to know. Once the delays grow past 10s, the restarts never hit the built-in start rate limit, and the service is restarted forever. Let's document the sum of the delays until RestartMaxDelaySec= is reached, using the formula proposed in #39197. Let's also show how to pick StartLimitBurst= and StartLimitIntervalSec= so the unit fails once the delay stops growing. A successful restart doesn't reset the restart counter. Earlier starts in the current start limit interval can change when the unit fails. Let's state the example's assumptions and document how to reset the restart counter and start rate limit. --- man/systemd.service.xml | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/man/systemd.service.xml b/man/systemd.service.xml index d0696ba868a..094961d5c64 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -643,6 +643,43 @@ RestartMaxDelaySec=160s steps. + The total wait until the first restart at RestartMaxDelaySec= is + + + (RestartMaxDelaySec * ratio - RestartSec) / (ratio - 1) + + , or 310s in the example above. This excludes the time each start, run, and stop + takes, and any delay added by RestartRandomizedDelaySec=. + + Use systemd-analyze restart-delays to show the restart delays and their + cumulative total, and check whether the start rate limit rejects a restart. See + systemd-analyze1. + + Restarts stop when the start rate limit is hit, see + StartLimitIntervalSec= and StartLimitBurst= in + systemd.unit5. + The defaults come from DefaultStartLimitIntervalSec= and + DefaultStartLimitBurst= in + systemd-system.conf5. + With the built-in defaults of 5 starts in 10s, the example restarts indefinitely. + + The start limit example below assumes that the restart counter and start rate limit are reset + before the first start, for example by systemctl reset-failed. Earlier starts in + the current rate limit interval may cause an earlier failure. If the interval expires during the + restart sequence, the service may restart indefinitely. A successful restart does not reset the + restart counter. After starting, the service can reset the restart counter with + RESTART_RESET=1, see + sd_notify3. + + To make the unit fail once the delay reaches RestartMaxDelaySec=, set + StartLimitBurst= to RestartSteps + 1, and set + StartLimitIntervalSec= to more than the total plus the time the service takes to + start, run, and stop each time. For the example above: + + [Unit] +StartLimitIntervalSec=10min +StartLimitBurst=5 + This setting is effective only if RestartMaxDelaySec= is also set and RestartSec= is not zero.