Aide-mémoire Nginx : commandes, extraits de configuration et corrections d'erreurs

12 min de lecture·Matthieu
web-servernginxreverse-proxycheatsheetlinux

Référence rapide pour les opérations Nginx quotidiennes sur Debian 12 et Ubuntu 24.04. Organisée par tâche pour trouver ce qu'il vous faut rapidement. Pour un guide complet, voir Administration Nginx sur un VPS.

Comment gérer le service Nginx ?

Utilisez systemctl pour contrôler Nginx via systemd, ou envoyez des signaux directement avec nginx -s. Systemctl est le standard sur les Debian et Ubuntu modernes. Les commandes natives nginx -s communiquent directement avec le processus maître via son fichier PID. Les deux fonctionnent. Systemctl est préférable pour l'automatisation et la persistance au démarrage.

Correspondance signaux et commandes

Action Commande systemctl Équivalent nginx -s Signal Unix Effet sur les workers
Démarrer sudo systemctl start nginx (non applicable) - Le processus maître démarre et lance les workers
Arrêt (gracieux) sudo systemctl stop nginx sudo nginx -s quit SIGQUIT Les workers terminent les requêtes en cours, puis s'arrêtent
Arrêt (immédiat) sudo systemctl kill nginx sudo nginx -s stop SIGTERM Les workers coupent les connexions et s'arrêtent
Recharger la config sudo systemctl reload nginx sudo nginx -s reload SIGHUP De nouveaux workers démarrent avec la nouvelle config. Les anciens terminent leurs requêtes, puis s'arrêtent. Aucune connexion perdue.
Rouvrir les logs (non intégré) sudo nginx -s reopen SIGUSR1 Les workers rouvrent les descripteurs de fichiers de log. À utiliser après la rotation des logs.
Activer au démarrage + démarrer sudo systemctl enable --now nginx (non applicable) - Crée le lien symbolique pour le démarrage, lance immédiatement
Désactiver + arrêter sudo systemctl disable --now nginx (non applicable) - Supprime le lien symbolique de démarrage, arrête immédiatement

enable --now fait survivre Nginx aux redémarrages et le lance immédiatement. Préférez toujours cette commande à un simple start.

Reload vs restart

reload envoie SIGHUP. Le processus maître lit la nouvelle config, lance de nouveaux workers et laisse les anciens terminer leurs connexions actives. Zéro interruption.

restart envoie SIGTERM (arrêt), puis redémarre à neuf. Toutes les connexions actives sont coupées. N'utilisez restart que pour changer les ports d'écoute, charger de nouveaux modules ou mettre à jour le binaire Nginx.

Testez toujours avant de recharger :

sudo nginx -t && sudo systemctl reload nginx

Si nginx -t échoue, le rechargement ne se déclenche pas. Votre config en production reste intacte.

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

Après le rechargement :

sudo 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: active (running) since Thu 2026-03-20 10:15:32 UTC; 2s ago

Le enabled dans la ligne Loaded signifie qu'il démarrera au boot. Installer Nginx sur Debian 12 et Ubuntu 24.04 depuis le dépôt officiel

Comment tester et inspecter la configuration Nginx ?

Lancez nginx -t pour valider la syntaxe sans toucher au serveur en cours d'exécution. Lancez nginx -T pour valider et afficher la config complète analysée sur stdout. Lancez nginx -V pour voir les modules et options de compilation.

Commande Objectif
sudo nginx -t Tester la syntaxe de la config, vérifier que les fichiers référencés existent
sudo nginx -t -q Même test, supprime la sortie non-erreur (utile dans les scripts)
sudo nginx -T Test + affichage de la config complète analysée sur stdout
sudo nginx -V Version, compilateur, arguments de configure, modules intégrés
sudo nginx -v Numéro de version uniquement

Afficher et rechercher dans la config active

sudo nginx -T 2>/dev/null | grep -A5 "server_name example.com"

Cette commande affiche la config complète (tous les fichiers inclus fusionnés), puis filtre un bloc server spécifique. Plus rapide que d'ouvrir les fichiers un par un quand vous avez des dizaines d'includes.

Vérifier les modules compilés

sudo nginx -V 2>&1 | tr ' ' '\n' | grep module

--with-http_ssl_module
--with-http_v2_module
--with-http_realip_module
--with-http_gzip_static_module
--with-http_stub_status_module

Vous ne pouvez pas utiliser une directive si son module n'est pas compilé. C'est la première chose à vérifier quand une directive provoque une erreur « unknown directive ».

Où se trouvent les fichiers de configuration et de logs Nginx ?

Sur Debian 12 et Ubuntu 24.04, le gestionnaire de paquets installe tout sous /etc/nginx/. Les logs vont dans /var/log/nginx/. Voici la structure complète.

Chemin Fonction
/etc/nginx/nginx.conf Config principale. Définit le nombre de workers, events, bloc http, includes
/etc/nginx/sites-available/ Fichiers de blocs server (disponibles mais pas forcément actifs)
/etc/nginx/sites-enabled/ Liens symboliques vers sites-available. Nginx charge ceux-ci.
/etc/nginx/conf.d/ Fragments de config additionnels. Chargés par l'include par défaut dans nginx.conf
/etc/nginx/snippets/ Extraits de config réutilisables (paramètres SSL, en-têtes de sécurité)
/etc/nginx/mime.types Table de correspondance des types MIME
/var/log/nginx/access.log Log des requêtes
/var/log/nginx/error.log Log des erreurs
/run/nginx.pid Fichier PID du processus maître

Pour activer un site :

sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Pour désactiver un site :

sudo rm /etc/nginx/sites-enabled/example.com
sudo nginx -t && sudo systemctl reload nginx

Pour une exploration détaillée de la structure des répertoires, voir Structure des fichiers de configuration Nginx.

Quels sont les extraits de configuration Nginx les plus courants ?

Chaque extrait ci-dessous est un exemple minimal fonctionnel. Copiez, adaptez les valeurs, testez avec nginx -t, rechargez. Pour des guides complets sur chaque sujet, suivez les liens internes.

Comment configurer un bloc server basique ?

Un bloc server (hôte virtuel) associe un domaine à un répertoire racine. Placez ceci dans /etc/nginx/sites-available/example.com.

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;

    root /var/www/example.com/html;
    index index.html;

    server_tokens off;

    location / {
        try_files $uri $uri/ =404;
    }
}

server_tokens off masque la version de Nginx dans les en-têtes de réponse. La divulgation de version aide les attaquants à cibler les vulnérabilités connues.

Créez un lien symbolique dans sites-enabled et rechargez. Nginx Server Blocks : héberger plusieurs domaines sur un VPS

Comment rediriger HTTP vers HTTPS ?

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;

    return 301 https://$host$request_uri;
}

return 301 est plus rapide que rewrite pour les redirections d'URL complètes. Nginx traite return avant de toucher au système de fichiers.

Comment configurer Nginx en reverse proxy ?

Transférez les requêtes vers un backend sur le port 3000. Placez ceci dans le bloc server HTTPS.

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Le slash final compte. proxy_pass http://127.0.0.1:3000; (sans slash final) transmet l'URI original complet. proxy_pass http://127.0.0.1:3000/; (avec slash final) supprime le préfixe du location. C'est la source de nombreuses configurations proxy cassées.

Configurer Nginx comme reverse proxy

Comment activer la compression gzip ?

Ajoutez au bloc http {} dans /etc/nginx/nginx.conf ou un fichier snippet :

gzip on;
gzip_vary on;
gzip_proxied any;
gzip_min_length 1024;
gzip_comp_level 5;
gzip_types
    text/plain
    text/css
    text/javascript
    application/json
    application/javascript
    application/xml
    image/svg+xml;

gzip_min_length 1024 ignore les fichiers de moins de 1 Ko. Compresser de petits fichiers ajoute de la charge CPU sans réduction de taille significative. gzip_comp_level 5 offre un bon équilibre entre taux de compression et coût CPU. Au-delà de 6, les gains diminuent.

Optimisation des performances Nginx sur un VPS

Comment ajouter une limitation de débit ?

Définissez une zone dans le bloc http {}, puis appliquez-la dans un bloc location ou server.

# In http {} block
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

# In server or location block
location /api/ {
    limit_req zone=api burst=20 nodelay;
    proxy_pass http://127.0.0.1:8080;
}

$binary_remote_addr utilise 4 octets par adresse IPv4. Une zone de 10 Mo contient environ 160 000 adresses. burst=20 autorise les pics courts. nodelay sert les requêtes en rafale immédiatement au lieu de les mettre en file d'attente.

Limiter le débit avec Nginx et se protéger contre les DDoS

Comment proxifier les connexions WebSocket ?

location /ws/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400s;
}

proxy_http_version 1.1 est obligatoire. HTTP/1.0 ne prend pas en charge l'en-tête Upgrade. proxy_read_timeout 86400s maintient les connexions WebSocket inactives ouvertes pendant 24 heures au lieu des 60 secondes par défaut.

Comment configurer des pages d'erreur personnalisées ?

server {
    error_page 404 /404.html;
    error_page 500 502 503 504 /50x.html;

    location = /404.html {
        root /var/www/errors;
        internal;
    }

    location = /50x.html {
        root /var/www/errors;
        internal;
    }
}

La directive internal empêche l'accès direct aux URL des pages d'erreur. Sans elle, les utilisateurs pourraient accéder directement à /404.html.

Comment ajouter des en-têtes de sécurité ?

Créez /etc/nginx/snippets/security-headers.conf :

add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;

Incluez-le dans n'importe quel bloc server :

include snippets/security-headers.conf;

Le paramètre always ajoute les en-têtes même sur les réponses d'erreur (4xx, 5xx). Sans lui, Nginx ne les ajoute que sur les 2xx/3xx. Durcissement de la sécurité Nginx sur Ubuntu et Debian

Bloc server TLS minimal

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name example.com;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers off;
    server_tokens off;

    # ... location blocks
}

N'activez pas TLSv1 ou TLSv1.1. Les deux ont des vulnérabilités connues et sont rejetés par les navigateurs modernes. Configurer Let's Encrypt SSL/TLS pour Nginx sur Debian 12 et Ubuntu 24.04

Comment lire et déboguer les logs Nginx ?

Nginx écrit deux logs par défaut : access.log pour chaque requête et error.log pour les problèmes. Les deux se trouvent dans /var/log/nginx/.

Suivre les logs en temps réel

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

Ou via journald :

journalctl -u nginx -f

Niveaux de sévérité du log d'erreurs

La directive error_log accepte un niveau. Du plus au moins verbeux :

debug > info > notice > warn > error > crit > alert > emerg

Le niveau par défaut est error. Pour activer temporairement le log de débogage :

error_log /var/log/nginx/error.log debug;

Rechargez Nginx. Le log de débogage est extrêmement verbeux. Désactivez-le après avoir diagnostiqué le problème, sinon il remplira votre disque.

Format de log d'accès en JSON

Les logs structurés sont plus faciles à analyser avec des outils comme jq, Loki ou OpenObserve.

log_format json_combined escape=json
    '{'
        '"time":"$time_iso8601",'
        '"remote_addr":"$remote_addr",'
        '"method":"$request_method",'
        '"uri":"$request_uri",'
        '"status":$status,'
        '"body_bytes_sent":$body_bytes_sent,'
        '"request_time":$request_time,'
        '"upstream_response_time":"$upstream_response_time",'
        '"http_user_agent":"$http_user_agent"'
    '}';

access_log /var/log/nginx/access.log json_combined;

Boîte à outils de débogage

Commande Ce qu'elle fait
curl -I https://example.com Affiche uniquement les en-têtes de réponse. Vérifiez le code de statut, la version du serveur, les en-têtes de cache.
curl -v https://example.com 2>&1 | head -30 Sortie détaillée : handshake TLS, en-têtes requête/réponse.
sudo nginx -T 2>/dev/null | grep server_name Liste tous les server_name configurés dans tous les fichiers de config.
sudo ss -tlnp | grep nginx Affiche sur quels ports/adresses Nginx écoute.
sudo ls -la /var/log/nginx/ Vérifie la taille et les permissions des fichiers de log.

Activer stub_status pour la supervision

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

curl http://127.0.0.1/nginx_status

Active connections: 3
server accepts handled requests
 1542 1542 4890
Reading: 0 Writing: 1 Waiting: 2

Restreignez stub_status à localhost ou à l'IP de votre outil de supervision. Cette directive expose des informations sur la charge du serveur.

Que signifient les codes d'erreur Nginx et comment les corriger ?

Quand Nginx renvoie une erreur HTTP, le fichier error.log indique ce qui s'est passé. Voici les codes les plus courants, leur signification et comment les corriger.

Code Nom Message typique dans error.log Cause courante Correction
403 Forbidden directory index of "/var/www/html/" is forbidden Fichier index manquant, mauvaises permissions, autoindex off (par défaut) Ajoutez un index.html, corrigez les permissions (chmod 644 pour les fichiers, 755 pour les répertoires), ou activez autoindex on
404 Not Found open() "/var/www/html/page" failed (2: No such file or directory) Mauvais chemin root, mauvais try_files, fichier inexistant Vérifiez la directive root, vérifiez le chemin du fichier sur le disque
413 Request Entity Too Large client intended to send too large body L'upload dépasse client_max_body_size (par défaut : 1 Mo) Définissez client_max_body_size 50m; dans le bloc server ou location
502 Bad Gateway connect() failed (111: Connection refused) while connecting to upstream Backend arrêté, mauvais port/socket dans proxy_pass Démarrez le backend, vérifiez que le port correspond au proxy_pass
503 Service Unavailable no live upstreams while connecting to upstream Tous les backends d'un bloc upstream sont arrêtés ou marqués down Démarrez au moins un backend, vérifiez la config de health check
504 Gateway Timeout upstream timed out (110: Connection timed out) while reading response header Le backend met trop de temps à répondre Augmentez proxy_read_timeout, optimisez le backend, consultez les logs du backend

Diagnostiquer un 502

Le 502 est l'erreur proxy la plus fréquente. Procédez étape par étape :

# 1. Is the backend running?
sudo ss -tlnp | grep 3000

# 2. Can Nginx reach it?
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:3000/

# 3. What does the error log say?
sudo tail -20 /var/log/nginx/error.log

Si ss ne montre rien sur le port 3000, le backend est arrêté. Si curl renvoie une réponse mais Nginx renvoie un 502, vérifiez les permissions des sockets (fréquent avec les sockets Unix PHP-FPM ou Gunicorn).

Quelles sont les erreurs Nginx les plus courantes ?

Ce sont elles qui causent la plupart des moments « j'ai modifié la config et maintenant c'est cassé ».

Points-virgules manquants

Chaque directive doit se terminer par un point-virgule. Nginx donne une erreur claire :

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

L'erreur pointe la ligne après le point-virgule manquant, pas la ligne du problème. Regardez une ligne au-dessus.

Confusion entre root et alias

# root: appends the location to the path
location /images/ {
    root /var/www;
    # serves /var/www/images/photo.jpg
}

# alias: replaces the location with the path
location /images/ {
    alias /var/www/media/;
    # serves /var/www/media/photo.jpg
}

Avec alias, le slash final est obligatoire sur le location et le chemin alias. L'oublier provoque des 404 sans raison apparente dans le log d'erreurs.

Confusion sur l'ordre de correspondance des location

Nginx évalue les locations dans cet ordre, quelle que soit leur position dans le fichier de config :

  1. = /exact - Correspondance exacte. Vérifiée en premier. Si elle correspond, arrêt immédiat.
  2. ^~ /prefix - Préfixe prioritaire. La correspondance la plus longue l'emporte. Si elle correspond, toutes les regex sont ignorées.
  3. ~ regex - Regex sensible à la casse. Évaluée de haut en bas. La première correspondance l'emporte.
  4. ~* regex - Regex insensible à la casse. Même ordre de haut en bas.
  5. /prefix - Préfixe standard. La correspondance la plus longue l'emporte. Utilisé uniquement si aucune regex n'a correspondu.

La longueur du préfixe compte, pas l'ordre dans le fichier de config. Pour les regex, c'est l'ordre dans le fichier qui compte, pas la longueur. Les mélanger sans comprendre cela crée un routage imprévisible.

Slash final dans proxy_pass

# No trailing slash: passes /app/foo to backend as /app/foo
location /app/ {
    proxy_pass http://127.0.0.1:3000;
}

# Trailing slash: strips /app/ and passes /foo to backend
location /app/ {
    proxy_pass http://127.0.0.1:3000/;
}

Choisissez l'un ou l'autre et restez cohérent. La plupart des backends attendent le chemin complet (sans slash final sur proxy_pass).

Oublier nginx -t avant le rechargement

Si vous rechargez avec une config cassée, Nginx continue de fonctionner avec l'ancienne config et journalise une erreur. Il ne plante pas. Mais vous avez maintenant une config sur disque qui ne correspond pas à la config en cours d'exécution. Cela crée de la confusion plus tard.

Prenez l'habitude : sudo nginx -t && sudo systemctl reload nginx. Le && garantit que le rechargement ne s'exécute que si le test réussit.

Modifier sites-available sans créer le lien symbolique

Les fichiers dans /etc/nginx/sites-available/ ne sont pas chargés automatiquement. Vous devez créer un lien symbolique vers /etc/nginx/sites-enabled/. Une copie directe fonctionne aussi, mais les liens symboliques maintiennent une source de vérité unique.

Quelque chose ne fonctionne pas ?

Séquence de diagnostic rapide quand Nginx se comporte mal :

# Check if Nginx is running
sudo systemctl status nginx

# Test the config
sudo nginx -t

# Check which config is actually loaded
sudo nginx -T 2>/dev/null | head -50

# Check the last 30 error log entries
sudo tail -30 /var/log/nginx/error.log

# Check what ports Nginx is listening on
sudo ss -tlnp | grep nginx

# Check file permissions on the web root
sudo ls -la /var/www/example.com/html/

Si le service est en échec, journalctl -u nginx --no-pager -n 50 donne l'histoire complète. Cherchez les entrées [emerg].

Prêt à essayer ?

Déployez votre serveur en quelques secondes. Linux, Windows ou FreeBSD. →