SSD Nodes Learn Hosting plans →
Anleitungen Matt ConnorVon Matt Connor · Aktualisiert 2026-10-28

Warum systemd Ihren Dienst nicht neu startet

Restart= überwacht nur den Hauptprozess. Ein beendeter Kindprozess in derselben cgroup bleibt unsichtbar. Erfahren Sie, wie Type=, Limits und das Journal wirken.

Die kurze Antwort: systemd-Neustartrichtlinien überwachen einen Prozess

systemd-Neustartrichtlinien überwachen pro Unit einen Prozess: den Hauptprozess. Restart= liest den Exit-Status dieses einen Prozesses sowie den Exit-Status der kurzen Befehle, die systemd selbst in diesem Zusammenhang ausführt, beispielsweise ExecStartPre=, ExecStartPost= und ExecReload=. Andere Informationen werden nicht ausgewertet. Die Control Group einer Unit kann zwanzig Prozesse enthalten. Einer dieser Prozesse kann beendet werden, während die Unit den Status active (running) behält, weil der Hauptprozess noch läuft. Für systemd ist nichts fehlgeschlagen, daher wird nichts neu gestartet.

systemd kennt die anderen Prozesse. Beim Stoppen der Unit beendet systemd sie, rechnet ihren Speicherverbrauch auf die Limits der Unit an, wendet das CPU-Kontingent der Unit auf sie an und zeigt sie in systemctl status an. Ihre Exit-Status werden jedoch nie ausgewertet. Die Neustartlogik und die Control Group sind zwei verschiedene Dinge. Der größte Teil dieses Leitfadens behandelt die Lücke zwischen beiden.

Was die cgroup enthält und welche Informationen die Neustartlogik auswertet

Eine cgroup (control group) ist ein Kernelobjekt, das eine Gruppe von Prozessen verwaltet. Jede Service-Unit erhält eine eigene cgroup mit dem Namen der Unit. Ein Prozess kann sie nicht verlassen. Kindprozesse übernehmen die cgroup ihres Elternprozesses. Ein Prozess ohne erhöhte Berechtigungen kann sich nicht in eine andere cgroup verschieben. Deshalb kann systemd auch einen Daemon zuverlässig bereinigen, der zweimal forkt. Alte init-Skripte konnten das nicht zuverlässig leisten.

Stellen Sie beide Informationen direkt gegenüber:

systemd-cgls --unit myapp.service
systemctl show -p MainPID -p NRestarts -p Restart -p RestartUSec myapp.service

systemd-cgls listet jeden Prozess in der Unit auf. MainPID ist die einzelne Zahl, die die Neustartrichtlinie auswertet. Wenn diese beiden Angaben nicht zu Ihrem mentalen Modell passen, liegt dort der Fehler. MainPID=0 bedeutet, dass systemd keinen Hauptprozess hat, von dem es einen Exit-Status auslesen kann. Die cgroup wird weiterhin überwacht. Daher erkennt systemd, wenn der letzte Prozess darin beendet wurde. Bis dahin hat die Neustartlogik jedoch keinen Exit-Status, den sie bewerten kann.

Es gibt eine echte Ausnahme von der Regel für den Hauptprozess. Wenn der Kernel-Out-of-Memory-Killer einen beliebigen Prozess innerhalb der cgroup der Unit beendet, erkennt systemd dies, weil es die Datei memory.events der cgroup überwacht. OOMPolicy= legt fest, was anschließend geschieht. Der Standardwert ist stop: Die gesamte Unit wird beendet, das Ergebnis wird als oom-kill aufgezeichnet und gilt damit als Fehler. Dadurch wird Restart=on-failure ausgelöst. Das Journal zeigt dies eindeutig.

myapp.service: A process of this unit has been killed by the OOM killer.
myapp.service: Failed with result 'oom-kill'.

Ein wegen Speichermangels beendeter Kindprozess fährt die Unit daher herunter. Ein Kindprozess, der durch einen Segmentation Fault beendet wird, tut dies dagegen nicht. Wenn Sie Speicherlimits für eine Unit festlegen, lesen Sie zunächst wie MemoryMax und CPUQuota auf die cgroup einer Unit angewendet werden, bevor Sie die Neustartrichtlinie anpassen. Denn diese beiden Funktionen greifen genau an dieser Stelle ineinander und sonst nirgends.

Wie Type= den Hauptprozess auswählt

Type= im Abschnitt [Service] betrifft nicht nur die Startreihenfolge. Damit wird festgelegt, welche PID (Prozess-ID) zu MainPID wird. Damit wird auch festgelegt, was Restart= sehen kann.

  • Type=simple ist der Standardwert. Der Prozess, den systemd aus ExecStart= forkt, ist der Hauptprozess. systemd markiert die Unit sofort als gestartet, bevor bekannt ist, ob exec überhaupt funktioniert hat. Ein Tippfehler im Pfad der Binärdatei führt dazu, dass der Startauftrag erfolgreich ist und Main process exited, code=exited, status=203/EXEC kurz danach.
  • Type=exec verhält sich wie simple, wartet beim Startauftrag jedoch, bis exec erfolgreich war. Dadurch wird der oben genannte Tippfehler korrekt als Startfehler gemeldet. Dafür ist systemd 240 oder neuer erforderlich. Ubuntu 20.04 und höher sowie Debian 12 enthalten diese Funktion. Ubuntu 18.04, das weiterhin über Ubuntu Pro unterstützt wird, enthält systemd 237 und nicht. Wenn dieser Wert verfügbar ist, verwenden Sie ihn bevorzugt gegenüber simple.
  • Type=forking erwartet, dass der Prozess aus ExecStart= einen Hintergrund-Daemon forkt und anschließend beendet wird. systemd wartet, bis der übergeordnete Prozess beendet ist, und sucht dann nach dem eigentlichen Daemon. Geben Sie PIDFile= an. Ohne diesen Wert funktioniert GuessMainPID= (standardmäßig aktiviert) nur, wenn genau ein Prozess in der Cgroup verbleibt. Bleiben zwei Prozesse zurück, bleibt MainPID auf 0.
  • Type=notify bedeutet, dass der Dienst sd_notify(3) aufruft und READY=1 sendet, sobald er Netzwerkverkehr verarbeiten kann. Er kann außerdem MAINPID= senden, um systemd einen anderen Prozess zur Überwachung zu übergeben. Bei Type=notify wird NotifyAccess= auf main gesetzt, sofern Sie keinen anderen Wert auswählen. Eine von einem untergeordneten Prozess gesendete Benachrichtigung wird daher ignoriert, und das Journal nennt die PID, von der sie stammt.
  • Type=oneshot hat keinen dauerhaft laufenden Hauptprozess. Die Unit wird inaktiv, sobald ExecStart= beendet ist, sofern Sie nicht RemainAfterExit=yes setzen. Restart=always und Restart=on-success werden hier mit der Meldung Service has Restart= set to either always or on-success, which isn't allowed for Type=oneshot services. Refusing. abgelehnt. Die anderen Werte, einschließlich on-failure, werden akzeptiert.

Zwei Type=forking-Fehler sollten Sie sich merken. Jeder davon führt zu einer Unit, die ohne sichtbaren Grund fehlerhaft wirkt:

myapp.service: Can't open PID file /run/myapp.pid (yet?) after start: No such file or directory
myapp.service: New main PID 4711 does not belong to service, and PID file is not owned by root. Refusing.

Der erste Fehler bedeutet, dass der Daemon seine PID-Datei an einer anderen Stelle schreibt oder sie erst schreibt, nachdem systemd danach gesucht hat. Der zweite bedeutet, dass die PID-Datei einen Prozess außerhalb der Cgroup der Unit angibt. systemd übernimmt diesen Prozess nicht. Andernfalls könnte eine beschreibbare PID-Datei dazu verwendet werden, systemd Signale an beliebige Prozesse auf dem Server senden zu lassen.

Warum ein Wrapper-Skript das Beenden seiner Kindprozesse verbirgt

Dies ist die Konstellation, die zur Frage aus der Überschrift führt.

#!/bin/bash
/usr/local/bin/myapp-web &
/usr/local/bin/myapp-worker &
wait

Die Unit ist Type=simple. Der Hauptprozess ist daher die Shell. wait ohne Argumente kehrt erst zurück, wenn alle Kindprozesse beendet wurden. Beenden Sie den Worker, wartet die Shell weiterhin auf den Webprozess. Deshalb beendet sich die Shell nicht, MainPID kehrt nicht zurück und Restart= wird nie ausgewertet. Die cgroup enthält jetzt einen Prozess weniger, systemctl status gibt den verkürzten Prozessbaum aus und die Unit bleibt active (running). systemd überwacht den Prozessbaum nicht auf Änderungen.

Eine zweite Variante desselben Fehlers ist unauffälliger:

ExecStart=/bin/sh -c 'export APP_ENV=production; /usr/local/bin/myapp'

Der Hauptprozess ist die Shell, nicht myapp. Bei systemctl stop sendet systemd SIGTERM an den Hauptprozess. Eine Shell, die auf einen Vordergrundprozess wartet, leitet das Signal nicht weiter. Der Stopp dauert dann die gesamte TimeoutStopSec, standardmäßig 90 Sekunden, und endet so:

myapp.service: State 'stop-sigterm' timed out. Killing.
myapp.service: Killing process 4711 (myapp) with signal SIGKILL.

Die Lösung ist exec. Schreiben Sie exec /usr/local/bin/myapp. Dadurch wird die Shell durch das Programm ersetzt, sodass MainPID das Programm ist und Signale dieses erreichen. Besser ist es, die Shell zu entfernen und in der Unit Environment= oder EnvironmentFile= zu verwenden. Beachten Sie, dass dieser Fehler verborgen bleibt, wenn die Zeichenkette -c nur einen Befehl enthält. bash und dash optimieren diesen Fall zu einem direkten exec. Fügen Sie der Zeichenkette einen zweiten Befehl hinzu, bleibt die Shell vor Ihrem Programm aktiv.

In zwei Minuten auf einem Test-VPS reproduzieren

Speichern Sie den obigen Wrapper als /usr/local/bin/two-children.sh, machen Sie ihn mit chmod +x ausführbar und ersetzen Sie die beiden Programmpfade durch sleep 3600. Verweisen Sie mit Type=simple und Restart=on-failure aus einer Unit darauf. Führen Sie anschließend systemctl daemon-reload aus und starten Sie die Unit. Führen Sie systemd-cgls --unit two-children.service aus und notieren Sie die drei PIDs: die Shell und ihre beiden Kindprozesse. Beenden Sie einen Kindprozess mit sudo kill <pid>. Prüfen Sie die Unit erneut. Der Prozessbaum ist um einen Prozess kürzer, der Status ist weiterhin active (running) und das Journal enthält keine neuen Meldungen. Führen Sie jetzt stattdessen sudo kill -9 <shell pid> aus. Die Unit schlägt fehl, der verbleibende Kindprozess wird beendet, weil KillMode=control-group der Standardwert ist, und das Journal zeigt Scheduled restart job, restart counter is at 1.

Die vollständige Restart=-Werteübersicht und wann on-failure besser als always ist

Restart= akzeptiert einen von sieben Werten. Der entscheidende Unterschied besteht darin, was als sauberer Exit gilt. systemd behandelt den Exit-Code 0, jeden in SuccessExitStatus= aufgeführten Code sowie bei jedem Typ außer Type=oneshot die Signale SIGHUP, SIGINT, SIGTERM und SIGPIPE als sauberen Exit. Alles andere gilt als unsauber, einschließlich SIGKILL und SIGSEGV.

  • no ist der Standardwert. Die Unit startet sich nie selbst neu. Deshalb beendet sich eine Unit ohne Zeile Restart= beim ersten Absturz und bleibt beendet.
  • on-success startet die Unit nur nach einem sauberen Exit neu.
  • on-failure startet die Unit nach einem Exit-Code ungleich 0, einem unsauberen Signal, einem Start- oder Stop-Timeout oder nach Ablauf des Watchdogs neu.
  • on-abnormal startet die Unit nach einem unsauberen Signal, einem Timeout oder nach Ablauf des Watchdogs neu, aber nie nach einem einfachen Exit-Code ungleich 0.
  • on-abort startet die Unit nur nach einem unsauberen Signal neu, also nach einem Absturz.
  • on-watchdog startet die Unit nur neu, wenn WatchdogSec= abläuft.
  • always startet die Unit nach jedem der oben genannten Fälle neu, einschließlich eines sauberen Exits mit Status 0.

on-failure ist der passende Standardwert für einen langlebigen Daemon. Damit wird ein Absturz behoben, während ein beabsichtigter exit 0 unbeachtet bleibt. always eignet sich für ein Programm, das aus Gründen außerhalb seiner Kontrolle sauber beendet wird, beispielsweise ein Tunnel-Client, der bei einer Trennung durch die Gegenstelle 0 zurückgibt. Der Nachteil von always besteht darin, dass Fehler verborgen werden: Ein Dienst, der startet, eine fehlerhafte Konfigurationsdatei liest, den Fehler protokolliert und sich mit Exit-Code 0 beendet, wird einfach erneut gestartet. Mit der standardmäßigen Pause von 100 Millisekunden erreicht er bald das weiter unten beschriebene Start-Ratenlimit und endet mit dem Status start-limit-hit als fehlgeschlagen. Mit einem ausreichend langen RestartSec= läuft er dagegen unbegrenzt weiter. Das einzige Anzeichen ist dann ein steigender Neustartzähler.

SuccessExitStatus= verschiebt die Grenze zwischen sauber und unsauber. Borg beendet sich bei Warnungen mit 1 und bei Fehlern mit 2. Eine Backup-Unit ohne SuccessExitStatus=1 wird daher jedes Mal als fehlgeschlagen markiert, wenn sie eine nicht lesbare Datei überspringt. RestartPreventExitStatus= führt Exit-Codes auf, die selbst unter always einen Neustart verhindern. So kann ein Programm sauber mitteilen, dass es nicht erneut gestartet werden soll. RestartForceExitStatus= bewirkt das Gegenteil. Ein Backup-Auftrag gehört in eine durch einen Timer gesteuerte Type=oneshot-Unit und nicht in eine Neustartschleife. Das Paar aus Service- und Timer-Unit, das einen Auftrag nach einem Zeitplan ausführt, ist dafür das passende Muster.

Beachten Sie beim Testen einen wichtigen Punkt. Wenn Sie Ihren Dienst mit einfachem kill <pid> beenden, wird SIGTERM gesendet. Dieses Signal steht auf der Liste der sauberen Exits. Restart=on-failure führt daher korrekterweise keinen Neustart durch, und Sie könnten fälschlich annehmen, Ihre Konfiguration sei fehlerhaft. Verwenden Sie stattdessen kill -9 <pid> oder systemctl kill -s SIGKILL myapp.service. Beachten Sie außerdem, dass kein Wert von Restart= nach systemctl stop greift oder wenn die Unit beendet wurde, weil eine BindsTo=- oder PartOf=-Abhängigkeit weggefallen ist. Ein Stop-Auftrag ist kein Fehler.

RestartSec und der Standardwert von 100 Millisekunden

RestartSec= ist die Pause zwischen dem Stoppen der Unit und dem erneuten Start durch systemd. Der Standardwert beträgt 100 Millisekunden. Prüfen Sie, welcher Wert für Ihre Unit tatsächlich geladen wurde:

systemctl show -p RestartUSec -p StartLimitIntervalUSec -p StartLimitBurst myapp.service

Für eine Unit, die diesen Wert nicht gesetzt hat, wird RestartUSec=100ms ausgegeben, sofern niemand DefaultRestartSec= in /etc/systemd/system.conf geändert hat. Dorther stammt der Wert, wenn er nicht gesetzt ist. Dieser Standardwert ist für einen Dienst geeignet, der einmal abstürzt und anschließend wieder startet. Für einen Dienst, der überhaupt nicht starten kann, ist er ungeeignet. Bei einem Programm, das sofort fehlschlägt, liegen der erste Start und vier Neustarts dann deutlich unter einer Sekunde. Damit sind die fünf Starts aufgebraucht, die das nachfolgend beschriebene Rate-Limit zulässt. Für alles, was auf eine Datenbank, einen Mount oder eine Netzwerkroute wartet, sollten Sie RestartSec=5s oder einen höheren Wert setzen.

Stand Oktober 2026 bieten systemd 254 und neuere Versionen außerdem RestartSteps= und RestartMaxDelaySec=. Diese Optionen erhöhen die Verzögerung von RestartSec= ausgehend über diese Anzahl von Versuchen bis zu einer Obergrenze. Ubuntu 24.04 wird mit systemd 255 ausgeliefert und unterstützt sie. Debian 12 wird mit systemd 252 ausgeliefert und unterstützt sie nicht, allerdings enthält bookworm-backports systemd 254. Wachsende Verzögerungen sind die richtige Lösung, wenn die Abhängigkeit längere Zeit nicht verfügbar sein kann.

Was „start request repeated too quickly“ wirklich bedeutet

Diesen Zustand halten viele Leser für ein willkürliches Aufgeben von systemd. Tatsächlich handelt es sich um einen Zähler. Die Regel lautet: Wird eine Unit innerhalb von StartLimitIntervalSec= mehr als StartLimitBurst=-mal gestartet, verweigert systemd einen weiteren Start und versetzt sie in den Zustand failed. Standardmäßig sind 5 Starts innerhalb von 10 Sekunden erlaubt.

Das Journal zeigt die Abfolge:

myapp.service: Scheduled restart job, restart counter is at 5.
myapp.service: Start request repeated too quickly.
myapp.service: Failed with result 'start-limit-hit'.
Failed to start myapp.service - My application.

und systemctl start enthält die bereits ausgeschriebene Lösung:

Job for myapp.service failed because start of the service was attempted too often. See "systemctl status myapp.service" and "journalctl -xeu myapp.service" for details. To force a start use "systemctl reset-failed myapp.service" followed by "systemctl start myapp.service" again.

systemctl reset-failed myapp.service setzt den Zähler und den Zustand failed zurück. Ohne diesen Befehl wird ein einfacher systemctl start weiterhin verweigert, bis das Zeitfenster StartLimitIntervalSec= abgelaufen ist. Automatische Neustarts bleiben deaktiviert, bis die Unit erneut gestartet wird. Auch manuelle Starts werden auf das Limit angerechnet. Daher können einige ungeduldige systemctl restart-Aufrufe während der Bearbeitung einer Konfigurationsdatei das Limit auslösen, ohne dass überhaupt ein Absturz vorliegt.

Der irreführende Teil: start-limit-hit nennt niemals den Grund für den Fehler des Dienstes. Die Meldung sagt nur, dass der Dienst wiederholt und in kurzer Folge fehlgeschlagen ist. Der eigentliche Grund steht in den darüberliegenden Journalzeilen.

Beide Einstellungen gehören in den Abschnitt [Unit]. Sie finden Beispiele, die diese Einstellungen in [Service] eintragen. Ältere systemd-Versionen haben das akzeptiert. Dadurch entsteht die Verwirrung. Tragen Sie die Einstellungen in [Unit] ein. Fragen Sie anschließend mit systemctl show ab, was systemd geladen hat. Nur der geladene Wert ist maßgeblich.

[Unit]
Description=My application
StartLimitIntervalSec=300
StartLimitBurst=5

[Service]
Type=exec
ExecStart=/usr/local/bin/myapp
Restart=on-failure
RestartSec=10s

Damit unternimmt die Unit innerhalb eines Zeitfensters von fünf Minuten fünf Startversuche, bevor systemd aufgibt. StartLimitIntervalSec=0 deaktiviert das Limit vollständig. Sie sollten sich über die Konsequenzen im Klaren sein: Ein Dienst, der niemals erfolgreich starten kann, wird nun unbegrenzt neu gestartet und schreibt bei jedem Versuch einen Eintrag in das Journal. Die systemweiten Standardwerte stehen in /etc/systemd/system.conf als DefaultStartLimitIntervalSec= und DefaultStartLimitBurst=.

Eine benachbarte Einstellung verdient eine Warnung. StartLimitAction= legt fest, was beim Erreichen des Limits geschieht. Zulässige Werte sind unter anderem reboot, reboot-force und poweroff. Der Standardwert ist none. Er versetzt die Unit in den Zustand failed und lässt das System unverändert. Auf einem entfernten VPS bedeutet poweroff, dass der Server ausgeschaltet bleibt, bis Sie die Konsole des Providers öffnen.

Ein Prozess pro Unit

Das ist fast immer die richtige Lösung. Wenn zwei Programme ausgeführt werden müssen, schreiben Sie zwei Units. Jede Unit hat dann einen echten Hauptprozess, einen echten Exit-Status und eine eigene Neustartrichtlinie. Außerdem erhalten Sie getrennte Logs, getrennte Ressourcenlimits und getrennte Neustartzähler. Das ist genau das, was Sie um drei Uhr morgens benötigen.

Beschreiben Sie die Beziehung zwischen den Units in den Unit-Dateien, nicht in einem Shell-Skript.

  • After= legt nur die Startreihenfolge fest. Über Fehler sagt es nichts aus.
  • Requires= startet die andere Unit zusammen mit dieser Unit und stoppt diese Unit, wenn die andere Unit ausdrücklich gestoppt wird.
  • BindsTo= ist Requires= plus der für Sie wichtige Fall: Diese Unit wird gestoppt, wenn die andere Unit aus irgendeinem Grund stoppt, auch bei einem Absturz. Kombinieren Sie es mit After=, da die Reihenfolge sonst nicht definiert ist.
  • PartOf= überträgt Stop- und Neustartvorgänge nach unten. Dadurch erreicht systemctl restart myapp.target jede Unit, die PartOf= ist.
  • Upholds= (systemd 249 und neuer, also Ubuntu 22.04 und neuer) hält die angegebene Unit am Laufen. Wenn sie stoppt, startet systemd sie erneut. Dabei gilt dasselbe Start-Ratenlimit wie für alle anderen Units.

Ein Worker, der niemals ohne seinen API-Server laufen darf und den systemd immer aktiv hält, solange die API läuft:

# /etc/systemd/system/myapp-api.service
[Unit]
Description=myapp API server
Wants=network-online.target
After=network-online.target
Upholds=myapp-worker.service

[Service]
Type=exec
User=myapp
ExecStart=/usr/local/bin/myapp serve
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target
# /etc/systemd/system/myapp-worker.service
[Unit]
Description=myapp background worker
BindsTo=myapp-api.service
After=myapp-api.service
StartLimitIntervalSec=120
StartLimitBurst=5

[Service]
Type=exec
User=myapp
ExecStart=/usr/local/bin/myapp worker
Restart=on-failure
RestartSec=5s

Der Worker hat keinen Abschnitt [Install] und wird niemals manuell aktiviert. Die API-Unit zieht ihn mit Upholds= hinzu. Daher ist systemctl enable --now myapp-api.service der einzige Befehl, den Sie ausführen müssen. Laden Sie die Konfiguration neu und prüfen Sie, wie systemd das Paar verarbeitet:

sudo systemctl daemon-reload
systemd-analyze verify /etc/systemd/system/myapp-worker.service
systemctl list-dependencies myapp-api.service

systemd-analyze verify gibt überhaupt nichts aus, wenn die Datei fehlerfrei ist. Jede Ausgabe weist auf ein Problem hin. Meist erkennt systemd einen Schlüssel in dem Abschnitt, in dem Sie ihn eingetragen haben, nicht oder eine Abhängigkeit verweist auf eine nicht vorhandene Unit.

Fix two: Type=notify, so systemd knows more than a PID

Wenn das Programm das systemd-Benachrichtigungsprotokoll unterstützt, sollten Sie es verwenden. Mit Type=notify teilt der Dienst systemd mit, wann er bereit ist. Dadurch wird die Startreihenfolge zuverlässig statt nur angenommen. Außerdem kann der Dienst mit MAINPID= den Prozess angeben, der relevant ist, statt auf einen Starterprozess zu verweisen.

WatchdogSec= ist den zusätzlichen Aufwand wert. Wenn Sie es setzen, muss der Dienst mindestens so häufig WATCHDOG=1 über sd_notify(3) senden. Sobald diese Nachrichten ausbleiben, beendet systemd den Dienst mit SIGABRT und markiert ihn als fehlgeschlagen. Restart=on-failure oder Restart=on-watchdog startet ihn dann erneut. Dies ist die einzige integrierte Möglichkeit, einen noch laufenden, aber festgefahrenen Prozess neu zu starten. Keine Richtlinie für Exit-Status kann diesen Zustand erkennen.

[Service]
Type=notify
NotifyAccess=main
ExecStart=/usr/local/bin/myapp serve
WatchdogSec=30s
Restart=on-failure
RestartSec=5s

Ein ausgelöster Watchdog erscheint im Journal als myapp.service: Watchdog timeout (limit 30s)!, gefolgt vom Beenden des Prozesses. Wenn die Unit stattdessen in activating (start) verbleibt, bis TimeoutStartSec abläuft, ist READY=1 entweder nicht eingetroffen oder wurde nicht gezählt. Entweder unterstützt das Programm das Protokoll nicht, oder NotifyAccess=main weist eine Benachrichtigung zurück, die von einem Kindprozess stammt. Das Journal meldet in diesem Fall beide PIDs. Möglich ist auch, dass ein Hilfsprozess die Nachricht gesendet und sich beendet hat, bevor systemd die zugehörige Unit ermitteln konnte. Diese letzte Nachricht wird selbst unter NotifyAccess=all ignoriert. Die Korrektur muss im Programm erfolgen: Es sollte sd_notify_barrier() aufrufen, bevor der Hilfsprozess beendet wird.

Bei Software mit einem HTTP-Health-Endpunkt, die jedoch keine Unterstützung für sd_notify bietet, gibt es zwei praktikable Möglichkeiten: eine kleine Timer-Unit, die den Endpunkt prüft und systemctl restart aufruft, oder die Prüfung durch eine Container-Laufzeitumgebung. Genau dafür gibt es Healthchecks in Compose und ihr Verhalten beim Neustart.

Korrektur drei: Ein Supervisor innerhalb der Unit, nur wenn es keine Alternative gibt

Manche Software wird tatsächlich als Bündel von Prozessen hinter einem Launcher ausgeliefert, das Sie nicht in einzelne Komponenten aufteilen können. Dann führen Sie innerhalb der Unit einen Supervisor aus und akzeptieren die Konsequenz: systemd überwacht den Supervisor, der Supervisor überwacht alle übrigen Prozesse, und Ihre Neustartrichtlinie ist nun in zwei Dateien definiert.

Die häufigste Ausprägung davon ist eine Container-Runtime. Eine docker compose- oder podman-Unit folgt genau diesem Muster. Die Neustartrichtlinie für die einzelnen Container wird in der Compose-Datei festgelegt, während die systemd-Unit nur dafür sorgt, dass die Runtime läuft. Wenn das Ihrer Struktur entspricht, zeigt die Unit, die einen Compose-Stack beim Booten startet die funktionierende Variante einschließlich der Begründung, warum Type=oneshot mit RemainAfterExit=yes dort normalerweise korrekt ist.

Die cgroup arbeitet weiterhin zu Ihrem Vorteil. Alles, was der Supervisor startet, bleibt in der cgroup der Unit. Daher decken MemoryMax=, CPUQuota= und die Bereinigung beim Stoppen weiterhin den gesamten Prozessbaum ab. Nur die Entscheidung über einen Neustart wird delegiert.

Unabhängig davon, welchen Supervisor Sie wählen, setzen Sie nicht unüberlegt Restart=always für die äußere Unit und zusätzlich eine aggressive Neustartrichtlinie innerhalb der Unit. Zwei Ebenen mit Neustartlogik und jeweils eigener Wartezeit führen zu einem Dienst, der minutenlang flapping zeigt, und zu einem Journal, das den Grund dafür nicht erklärt.

ExitType=cgroup bedeutet nicht „Neustart, wenn ein beliebiger Prozess beendet wird“

ExitType= (systemd 250 und neuer, also in Ubuntu 24.04 und Debian 12 enthalten) ist die Einstellung, die bei der Suche nach diesem Problem häufig gefunden wird. Sie bewirkt jedoch das Gegenteil von dem, was der Name nahelegt. Der Standardwert ExitType=main bedeutet, dass der Dienst als beendet gilt, sobald der Hauptprozess endet. Bei ExitType=cgroup gilt der Dienst als aktiv, bis der letzte Prozess in der cgroup beendet wird.

ExitType=cgroup macht eine Unit also unempfindlicher gegenüber dem Ende eines einzelnen Prozesses, nicht empfindlicher. Die Einstellung ist für ein Programm geeignet, das seinen eigentlichen Worker-Prozess als Fork startet und den übergeordneten Prozess beendet, ohne eine PID-Datei zu schreiben, sodass Type=forking den Daemon nicht finden kann. Für den hier beschriebenen Fehler ist sie nicht geeignet.

Es gibt keinen Wert Restart= mit der Bedeutung „Unit neu starten, wenn ein beliebiger Prozess in der cgroup beendet wird“. Wenn Sie dieses Verhalten benötigen, brauchen Sie einen Prozess pro Unit. Wenn sich das Programm nicht aufteilen lässt und Sie das Wrapper-Skript kontrollieren, kommt wait -n diesem Verhalten am nächsten. Der Befehl kehrt zurück, sobald der erste untergeordnete Prozess beendet wird:

#!/bin/bash
/usr/local/bin/myapp-web &
/usr/local/bin/myapp-worker &
wait -n
exit 1

Das Beenden eines beliebigen untergeordneten Prozesses beendet den Wrapper nun mit einem Status ungleich 0, sodass Restart=on-failure greift. Dies ist ein Kompromiss, keine Behebung. Sie erhalten weiterhin einen gemeinsamen Neustartzähler für zwei Programme, einen gemeinsamen Logdatenstrom und keine Möglichkeit, nur die fehlerhafte Hälfte neu zu starten.

Was tatsächlich passiert ist

Vier Befehle, in dieser Reihenfolge.

systemctl status myapp.service
systemd-cgls --unit myapp.service
systemctl show -p MainPID -p NRestarts -p Result -p ExecMainStatus myapp.service
journalctl -u myapp.service -b -o short-precise

systemctl status zeigt Status, Haupt-PID und den cgroup-Baum auf einem Bildschirm. Bei einer fehlerfreien Unit steht dort Active: active (running) mit einer Main PID:-Zeile, in der der erwartete Prozess genannt wird. Wenn der Baum unten Prozesse enthält, die Sie nicht erkennen, oder einen erwarteten Prozess nicht enthält, kennen Sie die Ursache bereits.

systemd-cgls --unit gibt denselben Baum ohne Kürzung aus. Das wird wichtig, sobald eine Unit mehr als eine Handvoll Prozesse verwaltet.

systemctl show gibt maschinenlesbare Informationen aus. NRestarts= ist der Neustartzähler. Damit erkennen Sie am schnellsten, ob ein Dienst bereits vierzigmal neu gestartet wurde oder seit dem Bootvorgang läuft. Result= enthält den Grund für den letzten Fehler: exit-code, signal, timeout, oom-kill, watchdog oder start-limit-hit. ExecMainStatus= ist der rohe Exit-Status des letzten Hauptprozesses.

Das Journal enthält die Abfolge. Nach diesen drei Zeilen sollten Sie suchen:

myapp.service: Main process exited, code=exited, status=1/FAILURE
myapp.service: Failed with result 'exit-code'.
myapp.service: Scheduled restart job, restart counter is at 1.

code=exited, status=N bedeutet, dass das Programm selbst N zurückgeben wollte. Der Fehler liegt dann im Programm oder in seiner Konfiguration. code=killed, signal=SEGV bedeutet, dass es abgestürzt ist. code=killed, signal=TERM bedeutet normalerweise, dass ein anderer Prozess den Dienst zum Beenden aufgefordert hat. Das ist kein Fehler und löst Restart=on-failure nicht aus. code=dumped bedeutet, dass eine Core-Datei hinterlassen wurde. coredumpctl list zeigt sie an, wenn systemd-coredump installiert ist.

Bei mehreren Rechnern ist NRestarts die relevante Zahl, die Sie regelmäßig erfassen sollten. Wenn der Zähler einer Unit jeden Tag steigt, schlägt der Dienst jeden Tag fehl, unabhängig davon, ob es jemand bemerkt. Sobald Sie mehr als zwei oder drei Rechner verwalten, macht eine einheitliche Methode zum Ausführen eines Befehls auf jedem Server daraus statt einer Vermutung einen Bericht.

FAQ

Warum meldet systemctl, dass mein Dienst aktiv ist, obwohl der Prozess beendet wurde?

systemd verfolgt pro Service-Unit einen Prozess, den Hauptprozess, und Restart= liest nur den Exit-Status dieses Prozesses. Alle anderen von der Unit gestarteten Prozesse befinden sich in derselben cgroup. systemd beendet diese Prozesse, wenn die Unit gestoppt wird, überwacht sie jedoch nie auf ihr Ende. Führen Sie systemctl show -p MainPID myapp.service aus und vergleichen Sie die Anzahl mit systemd-cgls --unit myapp.service. Wenn der beendete Prozess im Baum erscheint, aber nicht MainPID ist, hat systemd genau wie vorgesehen gearbeitet. Die Lösung besteht aus einem Prozess pro Unit. Die Beziehung zwischen den Units wird mit BindsTo= und Upholds= festgelegt.

Was bedeutet „start request repeated too quickly“?

Das bedeutet, dass die Unit innerhalb von StartLimitIntervalSec= mehr als StartLimitBurst=-mal gestartet wurde. Standardmäßig sind dies 5 Starts in 10 Sekunden. Deshalb hat systemd weitere Startversuche beendet. Dies ist eine Ratenbegrenzung. Sie erklärt nicht, warum der Dienst fehlschlägt. Lesen Sie daher die darüberstehenden Zeilen im Journal. Setzen Sie den Status mit systemctl reset-failed myapp.service zurück und beheben Sie anschließend den eigentlichen Fehler. Wenn der Dienst auf den langsamen Start einer Abhängigkeit wartet, erhöhen Sie RestartSec=. Mit dem Standardabstand von 100 Millisekunden werden alle fünf Versuche in weniger als einer Sekunde verbraucht.

Sollte ich Restart=always oder Restart=on-failure verwenden?

Verwenden Sie on-failure für fast alle Fälle. Damit wird ein Absturz, ein Exit mit einem Wert ungleich null, ein Timeout und das Auslösen eines Watchdogs verarbeitet. Ein absichtliches exit 0 bleibt dagegen unberührt. Verwenden Sie always nur, wenn das Programm aus Gründen außerhalb seiner Kontrolle sauber beendet wird, beispielsweise wenn ein Client beim Trennen seines Peers den Wert 0 zurückgibt. Der Nachteil von always besteht darin, dass ein Dienst mit einer fehlerhaften Konfiguration, der einen Fehler protokolliert und mit 0 beendet wird, immer wieder gestartet wird. Mit dem Standardabstand schlägt er bald mit start-limit-hit fehl. Mit einem längeren RestartSec= kann er unbegrenzt weiterlaufen. Dabei steigt NRestarts in systemctl show, was das einzige sichtbare Symptom sein kann.

Warum löst das manuelle Beenden meines Prozesses keinen Neustart aus?

Weil systemd bei jedem Typ außer Type=oneshot SIGHUP, SIGINT, SIGTERM und SIGPIPE als saubere Beendigungen wertet. Ein normales kill <pid> sendet SIGTERM. Bei Restart=on-failure gilt eine saubere Beendigung nicht als Fehler. Deshalb erfolgt kein Neustart. Die Konfiguration wirkt dann fehlerhaft, obwohl sie korrekt ist. Testen Sie mit kill -9 <pid> oder systemctl kill -s SIGKILL myapp.service. Dabei handelt es sich um eine nicht saubere Beendigung, die die Richtlinie auslöst. Dieselbe Regel erklärt, warum systemctl stop niemals gegen Ihre Neustartrichtlinie arbeitet.

Wo werden StartLimitIntervalSec und StartLimitBurst eingetragen?

Im Abschnitt [Unit]. Ältere Dokumentation und ältere systemd-Versionen ordnen sie [Service] zu. Daher unterscheiden sich kopierte Beispiele voneinander. Raten Sie nicht, welche Zuordnung Ihre Version berücksichtigt. Fragen Sie systemd nach systemctl daemon-reload mit systemctl show -p StartLimitBurst -p StartLimitIntervalUSec myapp.service und behandeln Sie diese Werte als maßgeblich. systemd-analyze verify /etc/systemd/system/myapp.service erkennt Schlüssel, die systemd überhaupt nicht kennt, und gibt nichts aus, wenn die Datei fehlerfrei ist.

War dieser Artikel hilfreich?

#systemd#restart#service-unit#cgroups#reliability