Codes de retour de systemctl : is-active, is-enabled, is-failed et signification du code LSB 3

Ce que c'est

systemctl mélange deux conventions de codes de retour différentes selon la sous-commande :

Sous-commande	0 signifie	non nul signifie
is-active PATTERN	au moins une unité correspondante est active	aucune ne l'est : 3 si inactive, 4 si inconnue (affiche l'état sauf avec --quiet)
is-failed PATTERN	au moins une unité correspondante est à l'état « failed »	aucune n'a échoué (1 ; 4 si inconnue)
is-enabled UNIT	activée, ou « static », « indirect », « generated », « alias »	par exemple « linked », « masked », « disabled » ; « not-found » donne 4
status [PATTERN|PID]	l'unité est active	suit l'ancienne table LSB ci-dessous

Pour systemctl status (et les autres vérifications de style LSB), le manuel de systemctl indique qu'il « uses the return codes defined by LSB, as defined in LSB 3.0.0 » (utilise les codes de retour définis par LSB, dans LSB 3.0.0) :

Valeur	Signification LSB	Usage par systemd
0	le programme est en cours d'exécution / service OK	l'unité est active
1	le programme est mort, le fichier PID de /var/run existe	l'unité n'a pas échoué (utilisé par is-failed)
2	le programme est mort, le fichier de verrou de /var/lock existe	inutilisé
3	le programme n'est pas en cours d'exécution	l'unité n'est pas active
4	l'état du programme ou du service est inconnu	unité inexistante

Le manuel ajoute une mise en garde explicite : « 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. » (La correspondance entre les états de service LSB et les états d'unité systemd est imparfaite ; il vaut donc mieux ne pas se fier à ces valeurs de retour, mais rechercher des états et sous-états d'unité précis.)

Pourquoi c'est important

Le code LSB 3 (« pas en cours d'exécution ») n'est pas une erreur d'exécution : systemctl indique simplement, et avec succès, que le service est arrêté. C'est un état parfaitement valide et courant (unité oneshot, service désactivé, unité volontairement arrêtée pour maintenance). Considérer tout code de retour non nul de systemctl comme le signe que l'appel à systemctl a échoué déclenchera une alerte pour une simple réponse du type « c'est juste arrêté ».

Comment l'appliquer

• Pour les vérifications scriptées, utilisez is-active, is-failed et is-enabled plutôt que d'analyser la sortie de status : chacune a une signification documentée et précise pour 0 et pour une valeur non nulle.
• Utilisez --quiet avec is-active, is-enabled et is-failed pour supprimer l'affichage de l'état et vous appuyer uniquement sur le code de retour dans les scripts.
• Si vous vous fiez à la table LSB (par exemple depuis un ancien wrapper de script init), rappelez-vous que 3 signifie « non active », ce qui inclut une unité en échec : utilisez donc is-failed pour distinguer une unité arrêtée d'une unité plantée. Le code 4 signifie que systemd ne connaît pas cette unité (faute de frappe, fichier d'unité manquant).
• Pour tout ce qui dépasse une simple vérification booléenne, préférez systemctl show -p ActiveState,SubState <unit>, conformément au conseil du manuel.

Pièges

• Supposer qu'un code non nul de is-active vaut toujours 1 : le systemd actuel (par exemple 255) renvoie 3 pour une unité inactive et 4 pour une unité inconnue, alors que is-failed renvoie 1 pour « pas en échec ».
• Déclencher une alerte sur tout code non nul de systemctl status <unit> dans un script de supervision, sans vérifier si la valeur est simplement 3 (arrêtée).