Exit-Codes von systemctl: is-active, is-enabled, is-failed und die Bedeutung von LSB-Code 3

Worum es geht

systemctl verwendet je nach Unterbefehl zwei unterschiedliche Konventionen für Exit-Codes:

Unterbefehl	0 bedeutet	Nicht-null bedeutet
is-active PATTERN	mindestens eine passende Unit ist aktiv	keine davon ist aktiv: 3 bei inaktiv, 4 bei unbekannt (gibt den Zustand aus, ausser mit --quiet)
is-failed PATTERN	mindestens eine passende Unit befindet sich im Zustand "failed"	keine davon ist fehlgeschlagen (1; 4 bei unbekannt)
is-enabled UNIT	enabled oder "static", "indirect", "generated", "alias"	z. B. "linked", "masked", "disabled"; "not-found" ergibt 4
status [PATTERN|PID]	Unit ist aktiv	folgt der älteren LSB-Tabelle unten

Für systemctl status (und andere Prüfungen im LSB-Stil) hält das systemctl-Handbuch fest, dass es "uses the return codes defined by LSB, as defined in LSB 3.0.0" (die in LSB 3.0.0 definierten Rückgabewerte verwendet):

Wert	Bedeutung nach LSB	Verwendung durch systemd
0	Programm läuft / Dienst OK	Unit ist aktiv
1	Programm ist beendet, PID-Datei in /var/run existiert	Unit nicht fehlgeschlagen (von is-failed verwendet)
2	Programm ist beendet, Lock-Datei in /var/lock existiert	nicht verwendet
3	Programm läuft nicht	Unit ist nicht aktiv
4	Status des Programms oder Dienstes ist unbekannt	keine solche Unit

Das Handbuch fügt ausdrücklich eine Warnung hinzu: "The mapping of LSB service states to systemd unit states is imperfect, so it is better to not rely on those return values but to look for specific unit states and substates instead." (Die Zuordnung von LSB-Dienstzuständen zu systemd-Unit-Zuständen ist unvollkommen; statt sich auf diese Rückgabewerte zu verlassen, sollten besser die konkreten Unit-Zustände und Unterzustände geprüft werden.)

Warum es wichtig ist

LSB-Code 3 ("läuft nicht") ist kein Ausführungsfehler: systemctl meldet damit erfolgreich, dass der Dienst schlicht gestoppt ist – ein völlig gültiger und häufiger Zustand (etwa bei einer oneshot-Unit, einem deaktivierten Dienst oder einer für Wartungsarbeiten absichtlich gestoppten Unit). Wer jeden Exit-Code ungleich null als fehlgeschlagenen systemctl-Aufruf behandelt, löst bei der alltäglichen Antwort «ist einfach aus» einen Alarm aus.

So wird es angewendet

• Für Prüfungen in Skripten is-active/is-failed/is-enabled verwenden, statt die Ausgabe von status zu parsen – jeder dieser Befehle hat eine dokumentierte, eng gefasste Bedeutung von 0 und Nicht-null.
• --quiet zusammen mit is-active/is-enabled/is-failed einsetzen, um die Ausgabe des Zustands zu unterdrücken und sich in Skripten allein auf den Exit-Code zu stützen.
• Wenn doch die LSB-Tabelle massgebend ist (z. B. bei einem älteren Wrapper für Init-Skripte), beachten: 3 bedeutet nicht aktiv – das schliesst auch eine fehlgeschlagene Unit ein, daher mit is-failed zwischen gestoppt und abgestürzt unterscheiden –, und 4 bedeutet, dass systemd diese Unit nicht kennt (Tippfehler, fehlende Unit-Datei).
• Für alles, was über eine einfache Ja/Nein-Prüfung hinausgeht, entsprechend der Empfehlung im Handbuch systemctl show -p ActiveState,SubState <unit> bevorzugen.

Stolpersteine

• Annehmen, dass ein Wert ungleich null von is-active immer 1 ist: Aktuelle systemd-Versionen (z. B. 255) geben für eine inaktive Unit 3 und für eine unbekannte 4 zurück, während is-failed für «nicht fehlgeschlagen» 1 liefert.
• In einem Monitoring-Skript bei jedem Wert ungleich null von systemctl status <unit> alarmieren, ohne zu prüfen, ob es sich einfach um 3 (gestoppt) handelt.