/config/systemd/restart-on-failure
systemd Restart=on-failure: restart a service automatically when it crashes
- tool
- systemd
- file
- /etc/systemd/system/NAME.service (or a drop-in .conf)
- key
- Restart
- type
- no | on-success | on-failure | on-abnormal | on-watchdog | on-abort | always
- default
- no
Restart=on-failure in the [Service] section tells systemd to start the service again when its main process exits with a non-zero code, is killed by a signal (other than the clean-exit signals), hits a timeout or a watchdog timeout. A clean exit with status 0 is not restarted; use Restart=always for that. Combine it with RestartSec= to wait between attempts. systemd stops retrying when the start rate limit is hit (by default 5 starts within 10 seconds) and marks the unit failed.
Add it with a drop-in
Do not edit the vendor unit in /usr/lib/systemd/system/. Create an override instead:
sudo systemctl edit myapp.service[Service]
Restart=on-failure
RestartSec=5s
[Unit]
StartLimitIntervalSec=300
StartLimitBurst=10systemctl edit reloads systemd for you when you save. If you write the file by hand, run sudo systemctl daemon-reload, then sudo systemctl restart myapp.service.
Which exits trigger a restart
| Value | Clean exit (0) | Non-zero exit | Signal | Timeout | Watchdog |
|---|---|---|---|---|---|
| no | - | - | - | - | - |
| always | yes | yes | yes | yes | yes |
| on-success | yes | - | - | - | - |
| on-failure | - | yes | yes | yes | yes |
| on-abnormal | - | - | yes | yes | yes |
| on-abort | - | - | yes | - | - |
| on-watchdog | - | - | - | - | yes |
"Signal" means an unclean signal; SIGHUP, SIGINT, SIGTERM and SIGPIPE count as a clean exit, and SuccessExitStatus= adds more exit codes that count as success. Stopping the service with systemctl stop never triggers a restart.
Related settings
| Setting | Section | Effect |
|---|---|---|
| RestartSec= | [Service] | Delay before restarting (default 100ms) |
| RestartSteps= / RestartMaxDelaySec= | [Service] | Grow the delay step by step up to a maximum (systemd 254+) |
| StartLimitIntervalSec= / StartLimitBurst= | [Unit] | More than Burst starts within Interval: give up and mark failed |
| RestartPreventExitStatus= | [Service] | Exit codes that must never cause a restart |
| OnFailure= | [Unit] | Unit to start when this one enters the failed state, for alerts |
When the rate limit stops the service, systemctl status shows start request repeated too quickly. After fixing the cause, clear it with sudo systemctl reset-failed myapp.service and start the service again.
Test it
systemctl show myapp.service -p Restart -p RestartUSec -p NRestarts
sudo systemctl kill -s SIGKILL myapp.service # simulate a crash
journalctl -u myapp.service -n 20 --no-pager # shows the scheduled restart