Pourquoi mon unité systemd ne démarre pas ?
Apprenez à interpréter les codes d'erreur systemd. Découvrez la signification des erreurs 203/EXEC et 226/NAMESPACE et pourquoi votre service s'arrête après un démarrage réussi.
Pourquoi une unité systemd ne démarre pas
Une unité systemd qui ne démarre pas indique la raison dans un champ. Exécutez systemctl status <unit>, puis recherchez code= et status= sur la ligne qui signale l’échec. Un code d’état dans les 200 signifie presque toujours que systemd n’a jamais lancé votre programme : l’échec s’est produit pendant la préparation de l’environnement demandé par votre fichier d’unité. Lorsque la ligne indique code=exited avec un code inférieur à 200, votre programme a bien été exécuté, puis s’est arrêté de lui-même. Le fichier d’unité est donc probablement correct et le problème vient de l’application. code=killed signifie qu’un signal a arrêté le processus. Il s’agit d’un cas distinct, traité vers la fin.
Cette distinction définit le chemin de diagnostic. La suite en découle, dans l’ordre où les codes apparaissent.
Les trois commandes qui répondent à la question, dans l’ordre
systemctl status myapp.service
journalctl -u myapp.service -b --no-pager
systemd-analyze verify /etc/systemd/system/myapp.servicesystemctl status donne le verdict. Lisez d’abord la ligne Loaded:, car elle indique le fichier que systemd a réellement analysé et précise si l’unité est activée, masquée ou totalement introuvable. Lisez ensuite la ligne Active:, puis les lignes code= et status= qui la suivent.
journalctl -u myapp.service -b --no-pager fournit les détails. -u filtre sur cette unité, -b limite la sortie au boot actuel pour éviter de lire une erreur de la semaine dernière, et --no-pager l’affiche directement dans le terminal afin que vous puissiez l’envoyer vers grep. status affiche uniquement les dernières lignes du journal et raccourcit les lignes trop longues. Le journal affiche tout ce que le programme a écrit avant de s’arrêter. Il contient généralement l’erreur réelle. Sans -n, vous obtenez toutes les entrées de ce boot. Ajoutez -n 100 pour ne conserver que les 100 dernières, ou exécutez la commande avec -f dans un second terminal pendant que vous redémarrez l’unité.
systemd-analyze verify charge un fichier d’unité sans l’exécuter. Cette commande signale les sections et directives inconnues. Elle signale aussi les commandes de ExecStart= qu’elle ne peut pas exécuter. Elle détecte deux catégories d’erreurs discrètes : une clé mal orthographiée, que systemd ignore au chargement en affichant un avertissement que la plupart des utilisateurs ne lisent jamais, et un chemin inexistant.
Après avoir modifié un fichier d’unité, exécutez sudo systemctl daemon-reload. Tant que vous ne l’avez pas fait, systemd continue d’utiliser la copie chargée précédemment, et systemctl status ajoute un avertissement indiquant que le fichier sur le disque a changé. Un correctif qui « n’a rien fait » est souvent un correctif que systemd n’a pas encore relu.
Deux autres commandes sont également utiles. systemctl cat myapp.service affiche l’unité effective, c’est-à-dire le fichier principal et tous les drop-ins situés sous /etc/systemd/system/myapp.service.d/. systemctl show myapp.service -p ExecStart -p User -p WorkingDirectory affiche ces valeurs telles que systemd les a analysées. Ce sont celles qui seront réellement utilisées.
Que signifie status=203/EXEC ?
203/EXEC signifie que systemd a terminé la préparation, a appelé execve(), puis que le kernel a refusé l’exécution. Votre programme n’a exécuté aucune ligne de son propre code. Quatre causes couvrent presque tous les cas.
- Le chemin indiqué dans
ExecStart=est incorrect ou n’est pas absolu. Vérifiez-le avecls -len le comparant à la chaîne exacte du fichier d’unité. - Le fichier n’a pas le bit d’exécution.
sudo chmod +x /opt/myapp/run.shcorrige le problème. Un fichier extrait d’une archive ou copié depuis une autre machine perd souvent ce bit. - La ligne shebang est incorrecte. Le kernel lit la première ligne d’un script et lance l’interpréteur qui y est indiqué.
#!/usr/bin/env python3échoue donc si le PATH du service ne contient paspython3. Un fichier enregistré avec des fins de ligne Windows demande un interpréteur nommé/bin/bash\r, qui n’existe pas. - Le fichier n’est pas exécutable par cette machine : architecture incorrecte ou fichier texte sans shebang.
Reproduisez le problème manuellement, avec l’utilisateur du service, avant de modifier quoi que ce soit.
sudo -u appuser /opt/myapp/run.sh
file /opt/myapp/run.sh
head -1 /opt/myapp/run.sh | cat -Afile indique l’architecture et affiche « with CRLF line terminators » lorsque les fins de ligne sont à l’origine du problème. cat -A affiche la même information sous la forme d’un ^M final. Supprimez-les avec sed -i 's/\r$//' /opt/myapp/run.sh.
Une précision importante sur cette plage : 200 et plus est une convention, pas une garantie. Votre propre programme peut quitter avec le code 203, et systemd ne peut pas distinguer les deux cas. systemd-analyze exit-status 203 affiche le nom et la classe de n’importe quel code, ce qui facilite la lecture du tableau. Toutefois, si votre application utilise des codes de sortie supérieurs à 199, modifiez-les.
Pourquoi les codes 217/USER ou 216/GROUP apparaissent-ils ?
217/USER signifie généralement que le compte indiqué dans User= n’existe pas au moment où le service démarre. Ce code couvre aussi l’échec de configuration de l’espace de noms utilisateur pour une option d’isolation telle que PrivateUsers=. Dans ce cas, le journal indique « Failed to set up user namespacing » au lieu de mentionner un utilisateur absent. 216/GROUP correspond au même échec pour Group= ou SupplementaryGroups=. Vérifiez chaque élément avec une commande.
getent passwd appuser
getent group appgroupChaque commande affiche une ligne, ou n’affiche rien et renvoie un code différent de zéro. L’absence de sortie signifie que le nom est inconnu du système. systemd ne peut donc pas basculer vers ce compte et s’arrête avant exec. Pour corriger le problème, créez le compte au lieu de définir User=root. Exécuter un service avec un compte système dédié doté du minimum de privilèges est précisément le rôle de cette directive.
sudo useradd --system --no-create-home --shell /usr/sbin/nologin appuserDynamicUser=yes contourne le problème en demandant à systemd d’allouer un compte temporaire à chaque démarrage. Cette solution convient à un service qui ne conserve aucun état. Tout service qui écrit des fichiers a également besoin de StateDirectory=, car l’ID utilisateur change entre les démarrages. Les fichiers créés dans un chemin ordinaire finissent alors associés à un compte qui n’existe plus.
Qu’est-ce que 226/NAMESPACE ?
226/NAMESPACE provient des directives de sandboxing. Lorsqu’une unité définit ProtectSystem=, ProtectHome=, PrivateTmp=, ReadWritePaths= ou une directive similaire, systemd crée un mount namespace privé pour ce service avant d’exécuter le programme. Ici, un namespace est une vue privée du système de fichiers pour un processus. Si un mount de ce plan échoue, le démarrage échoue avec le code 226 et votre programme ne s’exécute jamais.
La cause habituelle est un chemin indiqué dans ReadWritePaths= qui n’existe pas. ProtectSystem=strict monte tout le système de fichiers en lecture seule, et ReadWritePaths= rouvre les chemins nommés en écriture. systemd ne peut pas rouvrir un répertoire qui n’existe pas. Deux corrections conviennent. Laissez systemd créer le répertoire avec StateDirectory=, ce qui crée /var/lib/<name> à chaque démarrage et le donne à l’utilisateur du service, ou préfixez le chemin avec -, ce qui indique à systemd d’ignorer cette entrée lorsque la source est absente. La mauvaise correction consiste à supprimer le hardening, ce qui transforme un problème de cinq minutes en problème permanent.
[Service]
ProtectSystem=strict
ProtectHome=yes
StateDirectory=myapp
ReadWritePaths=-/srv/uploadsLorsque vous ne pouvez pas déterminer quelle ligne est responsable, supprimez tout le bloc de hardening, rechargez la configuration, puis démarrez le service. Si le service démarre, remettez les lignes une par une et redémarrez après chacune d’elles. Deux codes voisins de cette famille sont 233/RUNTIME_DIRECTORY et 238/STATE_DIRECTORY. Ils signifient que systemd n’a pas pu créer le répertoire indiqué dans RuntimeDirectory= ou StateDirectory=, ou s’en rendre propriétaire, généralement parce que ce chemin existe déjà et appartient à un autre utilisateur.
Pourquoi 200/CHDIR apparaît-il alors que WorkingDirectory semble correct ?
200/CHDIR signifie que le chdir() vers WorkingDirectory= a échoué. Le répertoire est absent ou l’utilisateur du service ne peut pas y accéder. Pour entrer dans un répertoire, il faut disposer de la permission d’exécution sur ce répertoire et sur chacun de ses répertoires parents. Ainsi, un /home/deploy/app parfaitement lisible reste inaccessible lorsque /home/deploy est en mode 700 et que le service s’exécute sous appuser.
sudo -u appuser test -x /srv/myapp && echo ok
namei -l /srv/myappnamei -l affiche le propriétaire et le mode de chaque composant du chemin. C’est le moyen le plus rapide de trouver le répertoire qui bloque l’accès au reste du chemin. Écrire WorkingDirectory=-/srv/myapp rend l’absence du répertoire non bloquante. C’est adapté à un programme qui n’a pas besoin de démarrer dans un emplacement précis, mais pas à un programme qui ouvre des fichiers avec un chemin relatif.
Pourquoi le service démarre-t-il, puis s’arrête-t-il une seconde plus tard ?
Ici, aucun code de la série 200 n’apparaît, et il n’y a souvent aucun message d’erreur. L’unité affiche inactive (dead) juste après le démarrage ou passe en boucle par activating (auto-restart). systemd a correctement préparé l’environnement. Le problème vient de l’écart entre le comportement de votre programme et ce que Type= indique qu’il doit faire.
Type=simple, la valeur par défaut, indique que le programme reste au premier plan. Si vous lui fournissez un daemon qui passe en arrière-plan par fork, puis se termine, systemd considère que le processus principal est terminé et marque le service comme achevé. La plupart des daemons disposent d’une option pour rester au premier plan, par exemple nginx -g 'daemon off;'.
Type=forking indique que le premier processus se termine dès que son processus enfant est prêt. Si vous lui fournissez un programme au premier plan, la tâche de démarrage attend jusqu’à l’expiration de TimeoutStartSec=, soit 90 secondes par défaut. systemd le tue alors et journalise un dépassement de délai.
Type=notify indique que le programme appelle sd_notify() pour signaler qu’il est prêt. Un programme qui ne prend pas cette fonction en charge ne signale rien. Le démarrage arrive donc à expiration et le journal enregistre le résultat comme un échec de protocole.
Choisissez le type en fonction du comportement réel du programme. Différences entre simple, forking, oneshot et notify est la décision qui permet de résoudre toute cette catégorie de problèmes.
Lorsqu’un service se termine à plusieurs reprises, systemd cesse d’essayer et indique que la demande de démarrage s’est répétée trop rapidement. L’unité reste alors en échec et systemd ne la redémarre pas automatiquement. Vous pouvez la démarrer manuellement une fois l’intervalle de limitation écoulé, ou exécuter sudo systemctl reset-failed myapp.service. Cette commande efface l’état d’échec et le compteur de redémarrages, ce qui permet de la démarrer immédiatement. Augmenter la limite ne fait que masquer le symptôme. Consultez le journal à partir du premier échec, et non du dernier, puis lisez ce que Restart=on-failure redémarre réellement avant de le modifier.
Pourquoi l’unité est-elle inactive sans afficher la moindre erreur ?
Une unité peut être ignorée au lieu d’être démarrée. Les directives Condition* sont silencieuses par conception : lorsque le contrôle échoue, systemd considère le job comme réussi et n’effectue aucune action. Une unité qui contient ConditionPathExists=/etc/myapp/config.yml ne démarrera jamais tant que ce fichier est absent, sans jamais signaler d’erreur.
systemctl show myapp.service -p ConditionResult -p ConditionTimestamp
journalctl -u myapp.service -b --no-pager | grep -i conditionConditionResult=no confirme que l’unité a été ignorée, et le journal indique quel contrôle n’a pas été satisfait. Utilisez plutôt une directive Assert* lorsqu’une condition préalable manquante doit provoquer une erreur explicite. La section Conditions, assertions et ordre de démarrage des unités explique quelle vérification utiliser à quel endroit.
D’autres cas silencieux se trouvent à proximité. Une erreur « could not be found » signifie généralement que le fichier se trouve dans le mauvais répertoire ou que vous n’avez pas rechargé la configuration : les fichiers d’unité que vous créez doivent se trouver dans /etc/systemd/system/. Une unité masquée refuse tout démarrage tant que sudo systemctl unmask myapp.service ne l’a pas démasquée. Enfin, systemctl enable échoue sur une unité qui ne contient aucune section [Install] ; ajoutez-lui donc WantedBy=multi-user.target.
Et si le processus avait été tué plutôt qu’en échec ?
code=killed est différent de code=exited. Quelque chose a terminé le processus depuis l’extérieur. status=9/KILL indique souvent l’action de l’out of memory (OOM) killer. Dans ce cas, le journal indique le processus sélectionné. SIGKILL n’indique toutefois pas qui l’a envoyé. systemd l’envoie également lorsqu’un service en cours d’arrêt ignore SIGTERM après TimeoutStopSec=. Vérifiez donc si un arrêt ou un redémarrage était en cours avant d’incriminer la mémoire. Une limite que vous avez définie vous-même produit le même effet dans le cgroup (control group). Vérifiez donc la mémoire disponible sur l’hôte avec free -m et recherchez un MemoryMax= dans l’unité. MemoryMax, CPUQuota et les autres limites des cgroups explique quelle limite tue un processus et laquelle le ralentit seulement.
status=15/TERM juste après une tentative de démarrage signifie généralement que systemd a dépassé le délai de démarrage et terminé le processus. Cela vous ramène à Type=.
Deux habitudes évitent la plupart de ces erreurs
Utilisez partout des chemins absolus. systemd n’exécute pas votre shell de connexion. Il n’y a donc pas de .bashrc, pas de .profile et pas d’environnement virtuel activé. $PATH d’un service système est une liste intégrée courte. Elle ne contient pas /opt ni les shims d’un gestionnaire de versions de langage. Écrivez /usr/bin/python3 ou /opt/myapp/venv/bin/python en entier. command -v myapp dans votre shell affiche le chemin à copier. La même règle s’applique à WorkingDirectory=, EnvironmentFile= et à tous les chemins de ReadWritePaths=.
ExecStart= n’est pas un shell. systemd découpe la ligne en mots et appelle directement execve(). Les pipes, redirections, jokers, &&, backticks et ~ n’ont aucune signification : ils sont transmis à votre programme comme des arguments littéraux. ExecStart=/usr/bin/myapp --flag > /tmp/out.log transmet > et /tmp/out.log à myapp, qui quitte ensuite avec une erreur d’utilisation sans rapport apparent avec un problème systemd. Lorsque vous avez besoin des fonctionnalités d’un shell, demandez l’exécution par un shell.
ExecStart=/bin/sh -c '/usr/bin/myapp --flag | /usr/bin/tee -a /var/log/myapp.log'Pour la seule sortie, ce n’est pas nécessaire. La sortie du service est envoyée au journal par défaut, et StandardOutput=append:/var/log/myapp.log écrit dans un fichier sans faire intervenir de shell.
L’expansion des variables est limitée de la même manière. $MYVAR et ${MYVAR} sont remplacées à partir de Environment=, EnvironmentFile= et des quelques variables que systemd définit lui-même, comme $USER. Les spécificateurs % tels que %i sont également développés. Rien provenant de votre shell de connexion n’est développé. $HOME est défini uniquement lorsque l’unité possède User=, via la valeur par défaut de SetLoginEnvironment=. Un service exécuté en tant que root sans User= ne possède donc pas $HOME, sauf si vous le définissez. Un EnvironmentFile= n’est pas non plus un script shell : export n’y a pas sa place, ses règles de citation diffèrent de celles de bash et un fichier manquant provoque une erreur fatale, sauf si vous préfixez le chemin avec -.
Procéder sur un serveur en production
Lisez le code, établissez la cause, modifiez une seule chose, puis redémarrez. Cet ordre est plus important que de connaître chaque valeur, car il évite d’empiler trois modifications spéculatives et de perdre la trace de celle qui a corrigé le problème. La même méthode s’applique aux unités que vous n’avez pas écrites. Un timer qui ne se déclenche jamais correspond à un service qui n’a jamais démarré. Commencez donc par déboguer le service : un timer systemd et le service qu’il déclenche échoue exactement pour les raisons indiquées ci-dessus, le timer masquant la sortie tant que vous ne la demandez pas au journal.
FAQ
Que signifie status=203/EXEC dans systemctl status ?
systemd a configuré tout ce que l’unité demandait, puis l’appel execve() a échoué. Votre programme n’a donc jamais démarré. Vérifiez quatre éléments dans l’ordre : le chemin indiqué dans ExecStart= existe et il est absolu, le fichier possède le bit d’exécution, le shebang désigne un interpréteur présent dans le PATH du service, et le fichier utilise des fins de ligne Unix. Pour ce dernier point, file affiche « with CRLF line terminators », ce qui transforme le nom de l’interpréteur en /bin/bash\r et amène le noyau à le refuser.
Pourquoi mon service démarre-t-il, puis s’arrête-t-il immédiatement ?
Le fichier d’unité décrit un comportement que le programme n’a pas. Avec Type=simple, systemd attend que le programme reste au premier plan. Un daemon qui se détache en arrière-plan semble donc terminé dès qu’il se fork. Avec Type=forking, systemd attend la fin du premier processus. Un programme au premier plan fait donc attendre la tâche de démarrage jusqu’à l’expiration de TimeoutStartSec=. Faites correspondre Type= au comportement du programme. Si celui-ci propose une option de premier plan, utilisez cette option avec la valeur par défaut Type=simple.
Comment voir l’erreur réelle au lieu de la sortie d’état abrégée ?
systemctl status affiche seulement les dernières lignes du journal et tronque les lignes longues. Exécutez journalctl -u myapp.service -b --no-pager pour afficher tout ce que l’unité a journalisé pendant ce boot. Ajoutez -n 200 pour ne conserver que les 200 dernières lignes, ou transmettez la sortie à grep. Si l’application écrit son propre fichier journal, consultez-le également. systemd ne capture que ce que le programme envoie vers la sortie standard et la sortie d’erreur standard.
Pourquoi mon unité est-elle inactive sans message d’erreur ?
Le plus souvent, une directive Condition* l’a ignorée. Ces vérifications sont silencieuses : si une condition échoue, la tâche de démarrage est considérée comme réussie. Exécutez systemctl show myapp.service -p ConditionResult et recherchez ConditionResult=no, puis lisez la ligne du journal qui indique le contrôle concerné. L’autre cause fréquente est une unité masquée. Elle refuse tout démarrage jusqu’à ce que sudo systemctl unmask la démasque.
Dois-je exécuter daemon-reload après chaque modification d’un fichier d’unité ?
Oui, pour toute modification d’un fichier d’unité ou d’un drop-in. sudo systemctl daemon-reload demande à systemd de relire les fichiers depuis le disque, puis sudo systemctl restart myapp.service applique ces changements au service en cours d’exécution. Cette commande est inutile après systemctl edit, qui effectue lui-même le rechargement. Elle est également inutile après la modification d’un fichier de configuration appartenant à l’application et non à systemd.