Dépanner un service Linux qui ne démarre pas avec systemd

Quand un service refuse de démarrer, la réponse est presque toujours dans systemctl status et journalctl -xeu. Ces deux commandes donnent l'état du service, le code de sortie et les dernières lignes de log. Dans 90 % des cas, l'erreur vient d'un fichier de configuration invalide, d'un port déjà occupé, d'une permission manquante ou d'une dépendance absente.

Ce que vous allez apprendre

• Appliquer une méthodologie de diagnostic en 5 étapes
• Lire et interpréter la sortie de systemctl status
• Cibler l'erreur avec journalctl -xeu
• Corriger les 7 causes les plus fréquentes d'échec
• Comprendre les codes de sortie de systemd
• Relancer proprement un service après correction

Dans quel contexte ?

Le dépannage de services est une compétence quotidienne d'administrateur :

• Vous venez d'installer Nginx ou PostgreSQL, le service ne démarre pas au premier essai
• Après une mise à jour de paquets, un service refuse de redémarrer à cause d'un changement de configuration
• Un service fonctionnait hier et passe en failed ce matin sans intervention apparente
• Vous avez modifié un fichier de configuration et le service ne redémarre plus
• Après un reboot, plusieurs services sont en failed, il faut diagnostiquer rapidement

LFCS / RHCSA

Le diagnostic de services systemd est un objectif central des deux certifications. Vous devez savoir identifier un service en échec, lire les journaux associés et corriger le problème dans un temps limité.

Méthodologie de diagnostic en 5 étapes

1. Vérifier l'état du service

   systemctl status nginx

   ● nginx.service - A high performance web server and a reverse proxy server
        Loaded: loaded (/usr/lib/systemd/system/nginx.service; enabled; preset: enabled)
        Active: failed (Result: exit-code) since Wed 2026-04-16 08:15:32 CEST; 2min ago
       Process: 1234 ExecStart=/usr/sbin/nginx (code=exited, status=1/FAILURE)
      Main PID: 1234 (code=exited, status=1/FAILURE)
           CPU: 12ms
   
   avr. 16 08:15:32 srv01 nginx[1234]: nginx: [emerg] bind() to 0.0.0.0:80 failed (98: Address already in use)
   avr. 16 08:15:32 srv01 systemd[1]: nginx.service: Main process exited, code=exited, status=1/FAILURE
   avr. 16 08:15:32 srv01 systemd[1]: nginx.service: Failed with result 'exit-code'.

   Les informations clés sont :

   • Active: failed, le service est en échec
   • Result: exit-code, le processus s'est terminé avec une erreur
   • status=1/FAILURE, le code de sortie
   • Les dernières lignes de log, ici, le port 80 est déjà occupé

2. Lire les journaux détaillés

   journalctl -xeu nginx

   Le flag -x ajoute des explications, -e saute à la fin, -u filtre par unité. C'est la commande la plus utile pour comprendre un échec.

   Pour voir les logs de la dernière tentative de démarrage :

   journalctl -u nginx --since "5 min ago"

3. Vérifier la configuration du service

   # Tester la syntaxe de la configuration
   nginx -t

   nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
   nginx: configuration file /etc/nginx/nginx.conf test is successful

   La plupart des services offrent une commande de test :

   Service	Commande de test
   Nginx	nginx -t
   Apache	apachectl configtest
   SSH	sshd -t
   Postfix	postfix check
   Named	named-checkconf

   Glissez pour voir

4. Identifier la cause et corriger

   Corriger le fichier de configuration, libérer le port, ajuster les permissions ou installer la dépendance manquante (voir les causes courantes ci-dessous).

5. Redémarrer et vérifier

   # Si le fichier unité a été modifié
   sudo systemctl daemon-reload
   
   # Redémarrer le service
   sudo systemctl restart nginx
   
   # Vérifier
   systemctl status nginx

Les 7 causes d'échec les plus fréquentes

1. Erreur de syntaxe dans la configuration

Symptôme : le service s'arrête immédiatement après le démarrage.

nginx: [emerg] unknown directive "server_nam" in /etc/nginx/sites-enabled/default:3

Correction : corriger la faute et tester la syntaxe avant de relancer.

2. Port déjà utilisé

Symptôme : bind() failed (98: Address already in use).

# Trouver quel processus occupe le port
sudo ss -tlnp | grep :80

LISTEN  0  511  0.0.0.0:80  0.0.0.0:*  users:(("apache2",pid=5678,fd=4))

Correction : arrêter le service concurrent ou changer le port.

3. Fichier ou répertoire manquant

Symptôme : No such file or directory dans les logs.

[emerg] open() "/var/log/nginx/access.log" failed (2: No such file or directory)

Correction :

sudo mkdir -p /var/log/nginx
sudo systemctl restart nginx

4. Permissions insuffisantes

Symptôme : Permission denied dans les journaux.

# Vérifier le propriétaire du fichier
ls -la /etc/nginx/ssl/

Correction : ajuster les permissions ou le propriétaire des fichiers concernés.

5. Dépendance absente (paquet, bibliothèque)

Symptôme : error while loading shared libraries ou command not found.

# Vérifier les bibliothèques manquantes
ldd /usr/sbin/nginx | grep "not found"

Correction : installer le paquet manquant.

6. Fichier unité incorrect

Symptôme : Failed to parse service type ou Invalid argument.

# Afficher le contenu du fichier unité
systemctl cat nginx.service

Correction : corriger le fichier unité, puis :

sudo systemctl daemon-reload
sudo systemctl restart nginx

daemon-reload obligatoire

Après toute modification d'un fichier .service, exécutez systemctl daemon-reload avant de redémarrer. Sans cela, systemd utilise l'ancienne version en mémoire.

7. Dépendance entre services (ordering)

Symptôme : le service démarre trop tôt, avant que le réseau ou la base de données ne soit prête.

# Vérifier les dépendances
systemctl cat monapp.service | grep -E "After|Requires|Wants"

Correction : ajouter les directives After= et Requires= dans la section [Unit] :

[Unit]
After=network.target postgresql.service
Requires=postgresql.service

Comprendre les codes de sortie

La sortie systemctl status affiche un code de sortie qui aide au diagnostic :

Les codes inférieurs à 125 viennent du programme lui-même. À partir de 200, c'est systemd qui n'a pas réussi à préparer l'environnement d'exécution : l'erreur est alors dans l'unité, pas dans le programme. Chaque code désigne précisément la directive fautive, ce qui accélère beaucoup le diagnostic.

Code	Nom systemd	Ce qui a échoué
0		Succès
1		Erreur générique : le programme a échoué de lui-même
2		Mauvais usage de la commande
200	EXIT_CHDIR	Le WorkingDirectory= est introuvable ou inaccessible
203	EXIT_EXEC	Le binaire d'ExecStart= est introuvable, non exécutable, ou son interpréteur est absent
209	EXIT_STDOUT	Impossible de mettre en place la sortie (StandardOutput=)
216	EXIT_GROUP	Le Group= n'existe pas, ou le changement de groupe a échoué
217	EXIT_USER	Le User= n'existe pas, ou le changement d'utilisateur a échoué
219	EXIT_CGROUP	Le service n'a pas pu être placé dans son cgroup
226	EXIT_NAMESPACE	Échec d'une directive d'isolation (PrivateTmp=, ProtectSystem=…)

Glissez pour voir

Les deux codes les plus fréquents sont 203 (le chemin d'ExecStart= est faux, ou le script n'a pas le bit d'exécution) et 217 (l'utilisateur déclaré dans l'unité n'existe pas sur la machine).

# Afficher le code de sortie exact
systemctl show nginx -p ExecMainStatus

Les états du service

systemctl list-units --state=failed

État	Signification
active (running)	Le service tourne normalement
active (exited)	Le processus s'est terminé avec succès (normal pour les services oneshot)
inactive (dead)	Arrêté proprement
failed	Le processus s'est terminé avec une erreur
activating	En cours de démarrage
deactivating	En cours d'arrêt

Glissez pour voir

Réinitialiser l'état failed

Après correction, si le service reste marqué failed :

sudo systemctl reset-failed nginx
sudo systemctl start nginx

Diagnostic avancé

Activer le mode debug d'un service

Pour obtenir une sortie verbose temporaire :

sudo systemctl edit nginx.service

Ajouter un override :

[Service]
Environment=NGINX_DEBUG=1

sudo systemctl daemon-reload
sudo systemctl restart nginx

Vérifier les limites de ressources

Un service peut échouer à cause de limites système (nombre de fichiers ouverts, mémoire) :

systemctl show nginx -p LimitNOFILE,LimitMEMLOCK,MemoryMax

Tester un service manuellement

Pour exécuter la commande ExecStart directement et voir l'erreur complète :

# Récupérer la commande de lancement
systemctl cat nginx.service | grep ExecStart

# L'exécuter manuellement
sudo /usr/sbin/nginx -t

Dépannage rapide

Symptôme	Cause probable	Solution
Active: failed (Result: exit-code)	Config invalide ou dépendance absente	journalctl -xeu service + corriger
Active: failed (Result: timeout)	Service trop long au démarrage	Augmenter TimeoutStartSec dans le fichier unité
Active: failed (Result: signal)	Processus tué (SIGKILL, OOM)	Vérifier dmesg | grep -i oom
code=exited, status=203/EXEC	Binaire introuvable ou non exécutable	Vérifier le chemin dans ExecStart
code=exited, status=200/CHDIR	Répertoire de travail manquant	Vérifier WorkingDirectory
Service démarre puis s'arrête	Type incorrect (forking vs simple)	Vérifier Type= dans la section [Service]
Job failed, see journalctl	Message générique	Exécuter journalctl -xeu service

Glissez pour voir

# Script de diagnostic rapide
systemctl status "$1"                          # État actuel
journalctl -xeu "$1" --no-pager --lines=20    # Derniers logs
systemctl cat "$1"                             # Fichier unité
systemctl show "$1" -p ExecMainStatus          # Code de sortie

Bonnes pratiques

• Toujours commencer par systemctl status + journalctl -xeu, ces deux commandes répondent à 90 % des questions
• Tester la configuration avant de relancer, nginx -t, sshd -t, apachectl configtest
• Exécuter daemon-reload après modification d'un fichier .service
• Ne pas ignorer les services en failed, systemctl list-units --state=failed doit être vérifié régulièrement
• Documenter les corrections, noter la cause dans un commentaire du fichier de configuration ou un runbook

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• systemctl status donne l'état, le code de sortie et les dernières lignes de log, c'est le point de départ
• journalctl -xeu service affiche les logs détaillés du service, c'est la commande de diagnostic principale
• Les 3 erreurs les plus fréquentes : configuration invalide, port occupé, permission manquante
• Après modification d'un fichier unité : daemon-reload puis restart
• Les codes de sortie (203, 200, 206…) orientent directement vers la cause
• systemctl reset-failed nettoie l'état failed après correction
• systemctl list-units --state=failed donne la vue globale de tous les services en erreur

×

📖 Voir la documentation →