Comment tester les configurations Nginx et surveiller l'état du serveur

Savoir comment tester les configurations Nginx et surveiller l'état du serveur évite que de petites erreurs ne deviennent des pannes. Un point-virgule manquant, un mauvais chemin de certificat ou un nom de serveur en double peut casser les rechargements, mais Nginx vous offre des outils fiables pour détecter les problèmes tôt.

Utilisez ces vérifications avant et après chaque modification de configuration, surtout sur les serveurs de production.

Tester la syntaxe de configuration Nginx

La première commande à exécuter est :

sudo nginx -t

Cela valide les fichiers de configuration chargés et indique si Nginx peut les analyser. Un résultat réussi ressemble à ceci :

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

Si le test échoue, ne rechargez pas. Lisez attentivement le message d'erreur. Nginx inclut généralement le chemin du fichier et le numéro de ligne :

nginx: [emerg] unexpected "}" in /etc/nginx/sites-enabled/example.com:42

Le numéro de ligne est le point de départ, pas toujours la réponse complète. Le vrai problème peut être un point-virgule ou une accolade manquante quelques lignes plus tôt.

Utilisez cette commande après toute modification de :

nginx.conf
Fichiers dans conf.d
Fichiers dans sites-enabled
Chemins de certificats TLS
Définitions de proxy upstream
Snippets inclus

Pour une vue complète de la configuration active, exécutez :

sudo nginx -T

Cela affiche le fichier principal et les fichiers inclus. C'est particulièrement utile lorsqu'une directive est définie dans un fichier que vous avez oublié.

Recharger en toute sécurité après un test réussi

Une fois que sudo nginx -t réussit, rechargez Nginx :

sudo systemctl reload nginx

Recharger est généralement plus sûr que redémarrer. Nginx démarre de nouveaux workers avec la nouvelle configuration tandis que les anciens workers terminent les requêtes existantes. Cela signifie que les utilisateurs sont moins susceptibles de voir des connexions interrompues.

Si le rechargement échoue, vérifiez l'état du service :

sudo systemctl status nginx

Puis vérifiez le journal :

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

Un flux de travail pratique ressemble à ceci :

sudo nginx -t
sudo systemctl reload nginx
sudo systemctl status nginx

Cette habitude en trois étapes détecte les erreurs de syntaxe, applique la modification et confirme que le service est resté sain.

Pour les opérations quotidiennes du service, consultez les commandes essentielles de contrôle du service Nginx.

Surveiller si Nginx sert du trafic

L'état du service vous indique si Nginx est en cours d'exécution. Cela ne prouve pas que les utilisateurs reçoivent les bonnes réponses. Vérifiez à la fois le processus et le comportement HTTP réel.

Confirmez que le service est actif :

systemctl is-active nginx

Confirmez que Nginx écoute sur les ports attendus :

sudo ss -ltnp | grep nginx

Vous devriez voir des écouteurs sur le port 80, le port 443, ou tout port personnalisé utilisé par votre configuration.

Ensuite, testez une réponse HTTP localement :

curl -I http://localhost

Pour HTTPS et les blocs de serveur nommés, incluez le nom d'hôte :

curl -I https://example.com

Si le DNS n'est pas encore pointé vers le serveur, vous pouvez tester avec une adresse résolue :

curl -I --resolve example.com:443:203.0.113.10 https://example.com

Remplacez l'IP par l'adresse de votre serveur. Cela vous permet de tester le bloc de serveur Nginx avant que les modifications DNS publiques ne soient appliquées.

Surveiller les journaux d'accès et d'erreurs

Les journaux montrent ce que fait Nginx après le rechargement. Les deux fichiers courants sont :

/var/log/nginx/access.log
/var/log/nginx/error.log

Suivez le journal d'erreurs en direct :

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

Suivez le journal d'accès en direct :

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

Le journal d'accès vous indique quelles requêtes arrivent et quels codes de statut Nginx renvoie. Le journal d'erreurs vous informe des connexions upstream échouées, des fichiers manquants, des problèmes de permissions, des limites de corps de requête, des problèmes TLS et des avertissements d'exécution liés à la configuration.

Cherchez des motifs, pas seulement des lignes isolées :

Beaucoup de réponses 404 peuvent signifier une mauvaise racine ou un mauvais bloc d'emplacement.
Beaucoup de réponses 502 peuvent signifier que l'application upstream est hors service.
Beaucoup de réponses 499 peuvent signifier que les clients abandonnent avant la fin de la réponse.
Des erreurs de permissions répétées peuvent signifier que la propriété des fichiers ou les bits d'exécution des répertoires sont incorrects.
Des erreurs de handshake TLS peuvent signifier un certificat ou un protocole incompatible.

Si vous hébergez plusieurs domaines, configurez des journaux séparés par bloc de serveur. Cela rend la surveillance plus propre et accélère la réponse aux incidents.

Activer les vérifications de base de l'état Nginx

Nginx inclut un module d'état léger dans de nombreuses versions. S'il est disponible, vous pouvez exposer un point de terminaison d'état local uniquement :

server {
    listen 127.0.0.1:8080;

    location /nginx_status {
        stub_status;
        allow 127.0.0.1;
        deny all;
    }
}

Interrogez-le depuis le serveur :

curl http://127.0.0.1:8080/nginx_status

Cela peut afficher les connexions actives et les compteurs de requêtes. Gardez ce point de terminaison privé. Ne l'exposez pas publiquement à moins qu'il ne soit protégé par des contrôles réseau appropriés.

Pour la surveillance en production, connectez les métriques et les journaux Nginx à votre pile d'observabilité habituelle. Les vérifications de base sont utiles, mais les tableaux de bord et les alertes sont meilleurs pour détecter les problèmes lorsque vous êtes absent.

Tester des scénarios réels, pas seulement la syntaxe

Une vérification de syntaxe peut réussir même si le comportement est incorrect. Après une modification, testez le chemin ou le domaine spécifique que vous avez touché.

Si vous avez modifié une redirection, testez à la fois l'ancienne et la nouvelle URL :

curl -I http://example.com/ancien-chemin

Si vous avez modifié les paramètres du proxy, testez une route API :

curl -i https://api.example.com/health

Si vous avez modifié la gestion des fichiers statiques, demandez une ressource réelle :

curl -I https://example.com/assets/app.css

Voici un scénario courant : vous ajoutez une nouvelle application monopage et nginx -t réussit. La page d'accueil fonctionne, mais rafraîchir /dashboard renvoie 404. Ce n'est pas un problème de syntaxe. Cela signifie généralement que votre bloc d'emplacement a besoin d'un fallback comme try_files $uri $uri/ /index.html;.

Quand demander de l'aide professionnelle

Demandez l'aide d'un ingénieur DevOps ou d'un spécialiste Nginx lorsque les échecs de rechargement affectent la production, lorsque les vérifications d'état ne correspondent pas aux rapports des utilisateurs, ou lorsque les erreurs impliquent des timeouts upstream, des échecs TLS, des équilibreurs de charge et le comportement CDN en même temps.

Vous devriez également escalader si vous voyez des crashs répétés, des sorties de workers inexpliquées, ou des erreurs qui persistent après avoir annulé la dernière modification de configuration. Le problème peut être extérieur à Nginx, comme des limites système, des échecs d'application ou du routage réseau.

Testez la syntaxe avant chaque rechargement, surveillez l'état après chaque modification et vérifiez le comportement réel des URL dont dépendent les utilisateurs. Cette simple discipline permet de détecter la plupart des problèmes de configuration Nginx avant qu'ils ne deviennent des incidents publics.