Maîtrise des commandes essentielles de Nginx pour le contrôle des services

Maîtriser les commandes essentielles de Nginx pour le contrôle des services vous aide à redémarrer en toute sécurité, à recharger la configuration sans perdre de trafic et à diagnostiquer pourquoi le serveur ne répond pas. La plupart du travail quotidien avec Nginx se résume à un petit ensemble de commandes utilisées avec précaution.

Ce guide se concentre sur l'utilisation pratique des commandes sur les systèmes Linux où Nginx est géré par systemd, ce qui est courant sur Ubuntu, Debian, CentOS, Rocky Linux et de nombreuses images cloud.

Les exemples supposent que le service s'appelle nginx. Certaines constructions personnalisées ou panneaux de contrôle utilisent un nom d'unité différent, mais les installations packagées de Nginx suivent généralement cette convention. En cas de doute, listez les unités correspondantes :

systemctl list-units '*nginx*'
systemctl list-unit-files '*nginx*'

Cette petite vérification évite une erreur courante : dépanner le mauvais service alors qu'un autre serveur web ou conteneur gère en réalité le trafic.

Vérifier si Nginx est en cours d'exécution

Commencez par l'état du service :

sudo systemctl status nginx

Cela indique si Nginx est actif, en échec, désactivé ou encore en cours de démarrage. Cela montre également les lignes de journal récentes de systemd, qui incluent souvent la raison pour laquelle un démarrage ou un rechargement a échoué.

Lisez attentivement les premières lignes d'état. active (running) signifie que systemd croit que le processus maître est vivant. failed signifie que la dernière tentative de démarrage ou de rechargement a échoué. enabled ou disabled vous indique le comportement au démarrage, pas si le service est en cours d'exécution maintenant.

Pour une sortie plus courte utile dans les scripts :

systemctl is-active nginx

Les sorties possibles incluent active, inactive, failed ou activating. Si vous avez seulement besoin de savoir si Nginx est activé au démarrage, utilisez :

systemctl is-enabled nginx

Vous pouvez également confirmer que Nginx écoute sur les ports web :

sudo ss -ltnp | grep nginx

Vous devriez voir des écouteurs sur des ports tels que 80 ou 443. Si le service est actif mais qu'aucun port attendu n'écoute, vérifiez vos directives listen et les fichiers de configuration inclus.

Si ss ne montre rien, confirmez si un autre processus a déjà le port :

sudo ss -ltnp 'sport = :80'
sudo ss -ltnp 'sport = :443'

Les conflits de ports sont courants après l'installation d'Apache, Caddy, d'un serveur de développement local ou d'un runtime de conteneur qui publie le même port. Dans ce cas, redémarrer Nginx à plusieurs reprises n'aidera pas. Vous devez arrêter le service en conflit ou changer l'écouteur.

Démarrer, arrêter, redémarrer et recharger Nginx

Utilisez start lorsque Nginx n'est pas en cours d'exécution :

sudo systemctl start nginx

Utilisez stop lorsque vous voulez intentionnellement le mettre hors ligne :

sudo systemctl stop nginx

Soyez prudent avec stop sur les serveurs de production. Cela rend immédiatement le service indisponible à moins qu'un autre serveur ou équilibreur de charge ne gère le trafic.

Utilisez restart lorsque vous avez besoin d'un arrêt et d'un démarrage complets :

sudo systemctl restart nginx

Un redémarrage est simple, mais ce n'est pas toujours le meilleur choix. Il peut interrompre les connexions actives, en particulier sur les serveurs chargés ou lorsque la configuration a des problèmes de démarrage.

Utilisez le redémarrage lorsque le processus Nginx lui-même est malsain, lorsqu'une mise à jour de module ou de package nécessite un nouveau processus, ou lorsque vous voulez délibérément effacer l'état des workers. Pour les modifications ordinaires de blocs serveur, les mises à jour de chemins de certificats, les changements d'amont, les redirections et les modifications d'en-têtes, le rechargement est généralement le meilleur premier choix.

Pour la plupart des modifications de configuration, préférez le rechargement :

sudo systemctl reload nginx

Un rechargement demande au processus maître Nginx de lire la nouvelle configuration et de démarrer de nouveaux workers. Les anciens workers terminent les requêtes existantes puis se ferment. C'est la manière normale d'appliquer les modifications avec moins de perturbations.

Un exemple pratique : vous ajoutez un nouveau bloc serveur pour api.example.com. Exécutez d'abord sudo nginx -t. Si le test réussit, exécutez sudo systemctl reload nginx. Les utilisateurs sur les connexions existantes ne devraient rien remarquer.

Vous pouvez également demander directement à Nginx de recharger :

sudo nginx -s reload

Sur les systèmes systemd, préférez systemctl reload nginx pour les opérations de routine car systemd reste la source de vérité pour l'état du service et les journaux. La forme directe nginx -s est encore utile sur les systèmes minimaux ou dans les conteneurs où systemd n'est pas présent.

Connaître la différence entre rechargement et redémarrage

Cette distinction évite beaucoup de temps d'arrêt évitables.

Un rechargement demande au processus maître Nginx de lire la nouvelle configuration et de démarrer de nouveaux workers. Si la configuration est valide, les nouveaux workers acceptent les nouvelles connexions tandis que les anciens workers terminent le travail existant et se ferment. C'est pourquoi le rechargement est le chemin de production normal.

Un redémarrage arrête et démarre le service. Selon le timing, le trafic et le comportement du superviseur, les clients peuvent voir des échecs de connexion. Un redémarrage peut également transformer une petite erreur de configuration en panne si Nginx fonctionnait auparavant avec une ancienne configuration valide et ne peut pas démarrer avec la nouvelle.

Un rythme sûr ressemble à ceci :

sudo nginx -t
sudo systemctl reload nginx
sudo systemctl status nginx --no-pager

Si le rechargement échoue, ne continuez pas à essayer. Lisez l'erreur exacte, corrigez le fichier, testez à nouveau, puis rechargez.

Tester la configuration avant d'appliquer les modifications

La commande la plus importante est :

sudo nginx -t

Cela vérifie la syntaxe et signale si Nginx peut charger la configuration. Cela détecte les points-virgules manquants, les mauvais chemins de fichiers, les directives en double, les modules inconnus et de nombreux problèmes de chemins de certificats.

Vous pouvez voir une sortie comme :

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

Si cela échoue, lisez attentivement le numéro de ligne. Nginx vous indique souvent le fichier et la ligne où l'analyse a échoué. La véritable erreur peut être juste au-dessus de cette ligne, surtout lorsqu'une accolade ou un point-virgule manque.

Pour imprimer la configuration complète chargée, y compris les fichiers inclus, utilisez :

sudo nginx -T

C'est utile lorsque vous n'êtes pas sûr du fichier qui contient une directive. Cela peut révéler des surprises provenant de /etc/nginx/conf.d/, sites-enabled ou des extraits fournis par le package.

nginx -T peut imprimer des chemins sensibles, des noms d'amont et parfois des valeurs de configuration intégrées. Soyez prudent lorsque vous collez la sortie complète dans des tickets, des discussions ou des forums publics. Rédigez les secrets et les noms d'hôtes internes si nécessaire.

Si vous gérez plusieurs instances Nginx ou des préfixes personnalisés, spécifiez explicitement le fichier de configuration :

sudo nginx -t -c /etc/nginx/nginx.conf

La plupart des systèmes packagés n'ont pas besoin de -c, mais c'est utile lorsque vous comparez une configuration candidate dans un chemin de staging.

Pour une liste de contrôle plus approfondie des commandes, consultez tester les configurations Nginx et surveiller l'état.

Consulter les journaux tout en contrôlant le service

Lorsqu'une commande échoue, les journaux expliquent généralement pourquoi. Commencez par le journal :

sudo journalctl -u nginx --since "10 minutes ago"

Pour un démarrage ou un redémarrage échoué, supprimez la fenêtre de temps et affichez les entrées récentes :

sudo journalctl -u nginx -n 100 --no-pager

Pour suivre les journaux en direct :

sudo journalctl -u nginx -f

Nginx écrit également ses propres journaux, généralement ici :

sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/log/nginx/access.log

Le journal systemd est le meilleur pour les erreurs de démarrage, d'arrêt, de rechargement et de permissions. Le journal d'erreurs Nginx est le meilleur pour les problèmes d'exécution tels que les échecs d'amont, les fichiers manquants, les limites de taille du corps client et les problèmes TLS.

Si votre serveur héberge plusieurs sites, vérifiez si chaque bloc serveur a ses propres fichiers journaux. Des journaux séparés facilitent grandement la connexion d'un changement de contrôle de service à un domaine spécifique cassé.

Après un rechargement, surveillez à la fois le journal et le journal d'erreurs pendant une minute :

sudo journalctl -u nginx -f
sudo tail -f /var/log/nginx/error.log

La commande de rechargement peut revenir rapidement, mais un amont cassé, un répertoire racine manquant ou un problème de permission peut n'apparaître que lorsque la première vraie requête atteint ce bloc serveur.

Activer ou désactiver Nginx au démarrage

Pour démarrer Nginx automatiquement après un redémarrage :

sudo systemctl enable nginx

Pour activer et démarrer en une seule étape :

sudo systemctl enable --now nginx

Pour l'empêcher de démarrer automatiquement :

sudo systemctl disable nginx

Désactiver n'arrête pas le service en cours d'exécution. Cela change seulement le comportement au démarrage. Si vous voulez désactiver et arrêter, exécutez à la fois disable et stop.

Sur les systèmes de production, confirmez le comportement au démarrage après la maintenance. Un serveur peut sembler sain après un démarrage manuel mais échouer à récupérer après le prochain redémarrage parce que Nginx n'a jamais été activé.

Si vous voulez confirmer l'ordre des dépendances, inspectez l'unité :

systemctl cat nginx
systemctl show nginx -p WantedBy -p After -p Requires

Évitez de modifier directement les fichiers d'unité packagés. Utilisez plutôt un remplacement :

sudo systemctl edit nginx

Cela crée un fichier d'insertion dans le répertoire de remplacement de systemd et maintient les mises à jour de package plus propres. Après avoir modifié les remplacements d'unité, exécutez :

sudo systemctl daemon-reload
sudo systemctl restart nginx

Ne modifiez les dépendances d'unité que lorsque vous comprenez la relation de démarrage. De nombreux problèmes Nginx appartiennent à la configuration Nginx, pas à la configuration systemd.

Envoyer des signaux seulement quand vous le voulez

Nginx a un processus maître et des processus workers. Le maître lit la configuration, gère les workers et répond aux signaux. Systemd cache la plupart de cela, ce qui est bon pour les opérations normales.

Si vous avez besoin d'inspecter l'arborescence des processus :

ps -o pid,ppid,user,cmd -C nginx

Vous verrez généralement un processus maître s'exécutant en tant que root et des processus workers s'exécutant en tant qu'utilisateur Nginx configuré, souvent www-data, nginx ou nobody selon la distribution.

Des signaux directs existent :

sudo nginx -s reload
sudo nginx -s quit
sudo nginx -s stop

quit demande un arrêt gracieux. stop se ferme rapidement. Dans l'administration système quotidienne, utilisez systemctl sauf si vous avez une raison spécifique de ne pas le faire. Cela maintient l'état du service, les journaux et le comportement de redémarrage au même endroit.

Erreurs de commande courantes à éviter

Ne rechargez pas après un test de configuration échoué. Le rechargement devrait échouer, mais compter là-dessus est négligent et rend le dépannage plus bruyant.

N'utilisez pas kill -9 pour le contrôle normal de Nginx. Laissez systemd et le processus maître Nginx gérer les workers. Forcer l'arrêt des processus peut laisser des états confus et des connexions interrompues.

Ne modifiez pas les fichiers dans sites-available en supposant qu'ils sont actifs. Sur les dispositions de style Debian, le fichier activé est généralement un lien symbolique dans sites-enabled. Confirmez avec :

ls -l /etc/nginx/sites-enabled/

N'oubliez pas les permissions des fichiers de certificats. Si Nginx ne peut pas lire un certificat ou une clé pendant le rechargement, les blocs serveur HTTPS peuvent échouer à se charger.

Ne supposez pas que sudo systemctl status nginx prouve que chaque site fonctionne. Nginx peut être en cours d'exécution tandis qu'un bloc serveur pointe vers un amont mort ou une racine de document erronée.

Ne testez pas seulement HTTP lorsque la modification concerne HTTPS. La chaîne de certificats, les permissions de clé, la correspondance SNI et le comportement de redirection nécessitent tous une vérification HTTPS :

curl -I https://example.com/
openssl s_client -connect example.com:443 -servername example.com </dev/null

curl -I suffit pour de nombreuses vérifications. openssl s_client est plus verbeux et utile lorsque vous avez besoin d'inspecter le certificat servi par un nom spécifique.

Une liste de contrôle sécurisée pour les modifications en production

Pour une petite modification de configuration Nginx, utilisez une liste de contrôle reproductible :

Modifiez le fichier prévu.
Exécutez sudo nginx -t.
Si le test échoue, corrigez la configuration avant de toucher au service en cours d'exécution.
Exécutez sudo systemctl reload nginx.
Vérifiez sudo systemctl status nginx --no-pager.
Testez l'URL affectée avec curl.
Surveillez le journal d'erreurs pour de nouveaux messages.

Par exemple, après avoir ajouté une redirection :

sudo nginx -t
sudo systemctl reload nginx
curl -I http://example.com/old-path
sudo tail -n 50 /var/log/nginx/error.log

Pour un changement de proxy inverse, testez le chemin amont réel :

curl -I https://api.example.com/health
sudo journalctl -u nginx --since "5 minutes ago" --no-pager

C'est ennuyeux à dessein. La plupart des pannes Nginx dues à des modifications de configuration surviennent parce que quelqu'un a sauté le test, rechargé le mauvais hôte ou n'a pas vérifié la route affectée.

Dépannage des démarrages et rechargements échoués

Si Nginx ne démarre pas, exécutez d'abord le test de configuration :

sudo nginx -t

Si la syntaxe est valide mais que le démarrage échoue toujours, vérifiez le journal :

sudo journalctl -u nginx -n 100 --no-pager

Les causes courantes incluent :

Un autre processus utilise déjà le port 80 ou 443.
Le chemin d'un fichier de certificat ou de clé est erroné.
Nginx ne peut pas lire un fichier à cause de permissions ou d'une politique SELinux/AppArmor.
Un répertoire référencé n'existe pas.
Un module dynamique configuré dans nginx.conf est manquant après un changement de package.

Pour les conflits de ports :

sudo ss -ltnp 'sport = :80'
sudo ss -ltnp 'sport = :443'

Pour les fichiers manquants, faites confiance au message d'erreur Nginx. Il nomme généralement le chemin. Vérifiez le chemin exactement comme écrit, pas le chemin attendu :

sudo ls -l /path/from/error/message

Si un rechargement échoue mais que Nginx est toujours en cours d'exécution, l'ancienne configuration peut encore être active. C'est une bonne nouvelle : les utilisateurs peuvent ne pas être encore affectés. Corrigez la configuration, testez à nouveau et rechargez à nouveau. Ne redémarrez pas sauf si vous savez que la configuration active peut démarrer proprement.

Quand escalader les problèmes de contrôle de service

Appelez un ingénieur DevOps ou un administrateur Linux lorsque Nginx ne démarre pas après une mise à jour de package, lorsque les rechargements échouent sur un serveur de production, ou lorsque systemd montre des erreurs de permission et de sandboxing que vous ne comprenez pas. Demandez également de l'aide avant de modifier les fichiers d'unité sur une infrastructure partagée.

Si Nginx se trouve derrière un équilibreur de charge, coordonnez les redémarrages avec les vérifications de santé et le comportement de drainage. Une commande locale peut avoir des effets plus larges que prévu.

Le rythme le plus sûr est simple : vérifiez l'état, testez la configuration, rechargez quand c'est possible, redémarrez seulement quand c'est nécessaire, et lisez les journaux immédiatement après les modifications. Ces habitudes rendent le contrôle des services Nginx prévisible plutôt que stressant.