Nginx : structure de la configuration

Comprendre comment Nginx organise sa configuration évite l’essentiel des erreurs. Les exemples utilisent des noms génériques.

Structure en blocs

Le fichier /etc/nginx/nginx.conf est un ensemble de directives (nom valeur;) et de blocs (nom { … }) imbriqués :

user www-data;
worker_processes auto;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

Contexte	Contenu
principal	Réglages généraux (utilisateur, nombre de processus)
`events`	Gestion des connexions
`http`	Réglages communs à tous les sites web
`server`	Un site (un nom de domaine, un port)
`location`	Traitement d’un chemin d’URL dans un `server`
`upstream`	Groupe de serveurs pour le reverse proxy

Une directive déclarée dans un contexte s’applique à ses enfants, sauf si elle est redéfinie plus bas. Chaque directive est terminée par ; : une omission est l’erreur la plus courante.

Découpage sur Ubuntu

nginx.conf inclut tous les fichiers de sites-enabled/ : un fichier par site.

/etc/nginx/
├── nginx.conf
├── sites-available/        ← un fichier par site (le travail se fait ici)
│   ├── default
│   └── exemple.com
├── sites-enabled/          ← liens symboliques vers sites-available
│   └── exemple.com -> ../sites-available/exemple.com
├── snippets/               ← fragments réutilisables (include)
└── conf.d/                 ← configurations supplémentaires (*.conf)

sudo ln -s /etc/nginx/sites-available/exemple.com /etc/nginx/sites-enabled/      # activer
sudo rm /etc/nginx/sites-enabled/exemple.com                                     # désactiver

Méthode sûre pour modifier

sudo cp /etc/nginx/sites-available/exemple.com /etc/nginx/sites-available/exemple.com.bak   # copie de secours
sudo nano /etc/nginx/sites-available/exemple.com
sudo nginx -t                            # 1. tester
sudo systemctl reload nginx              # 2. appliquer sans coupure
sudo tail -n 20 /var/log/nginx/error.log # 3. vérifier

Si nginx -t signale une erreur, ne rien recharger : corriger d’abord. Un rechargement avec une configuration invalide est ignoré (l’ancienne reste active), alors qu’un redémarrage (restart) échoue et coupe le service.

Commande	Effet
`sudo nginx -t`	Teste la syntaxe
`sudo nginx -T`	Teste et affiche la configuration complète
`sudo systemctl reload nginx`	Recharge la configuration, sans couper les connexions
`sudo systemctl restart nginx`	Redémarre (coupe brièvement le service)
`sudo nginx -V`	Version et modules de compilation

Choix du `server` : `listen` et `server_name`

Nginx choisit le bloc server selon le port (listen), puis le nom d’hôte demandé (server_name) :

server {
    listen 80;
    server_name exemple.com www.exemple.com;
    # …
}

server {
    listen 80 default_server;          # reçoit les requêtes qui ne correspondent à aucun nom
    server_name _;
    return 444;                        # ferme la connexion sans répondre
}

return 444 pour le serveur par défaut évite que le serveur réponde à des requêtes visant une adresse IP ou un domaine inconnu.

Choix du `location` : ordre de priorité

Forme	Type	Exemple
`location = /chemin`	Correspondance exacte	`location = /sante { … }`
`location ^~ /prefixe/`	Préfixe prioritaire (ignore les expressions régulières)	`location ^~ /assets/ { … }`
`location ~ regex`	Expression régulière, sensible à la casse	`location ~ \.php$ { … }`
`location ~* regex`	Expression régulière, insensible à la casse	`location ~* \.(png\|jpg)$ { … }`
`location /prefixe`	Préfixe simple	`location /api/ { … }`

Ordre d’évaluation : exact (=), puis le préfixe le plus long (si ^~, on s’arrête), puis les expressions régulières dans l’ordre d’écriture, puis le préfixe le plus long retenu.

`root`, `alias` et `try_files`

server {
    root /var/www/exemple.com;                       # racine du site
    index index.html;

    location / {
        try_files $uri $uri/ =404;                   # fichier, puis dossier, puis erreur 404
    }

    location /images/ {
        alias /srv/images/;                          # /images/a.png -> /srv/images/a.png
    }
}

root ajoute le chemin de l’URL : location /images/ { root /srv; } sert /srv/images/a.png.
alias remplace la partie du chemin correspondant au location.
Pour alias, terminer location et alias par / ensemble (ou ni l’un ni l’autre).
try_files essaie les options dans l’ordre ; la dernière est la valeur de repli (un code d’erreur ou une URI).

Variables courantes

Variable	Contenu
`$host`	Nom d’hôte demandé
`$uri`	Chemin demandé (normalisé, sans paramètres)
`$request_uri`	Chemin et paramètres tels que reçus
`$args`	Paramètres de requête
`$scheme`	`http` ou `https`
`$remote_addr`	Adresse du client
`$request_method`	`GET`, `POST`…
`$status`	Code de réponse (dans les journaux)

Fragments réutilisables : `include` et snippets

sudo tee /etc/nginx/snippets/securite.conf <<'CONF'
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
CONF

server {
    # …
    include snippets/securite.conf;
}

Pièges fréquents

Piège	Explication
`;` oublié	`nginx -t` indique la ligne suivante : regarder la ligne précédente
`proxy_pass http://app:3000/;` avec ou sans `/` final	Change le chemin transmis (voir Reverse proxy)
`add_header` dans un `location`	Remplace tous les `add_header` du niveau supérieur (voir Sécurité)
`if` dans un `location`	À éviter sauf `return` et `rewrite` simples : comportement surprenant
Modification non prise en compte	Oubli de `reload`, ou fichier non activé dans `sites-enabled`

Dépannage

sudo nginx -t                                  # erreur de syntaxe : ligne et fichier indiqués
sudo tail -f /var/log/nginx/error.log          # pendant un test de requête
curl -I -H "Host: exemple.com" http://127.0.0.1/chemin

Pour aller plus loin

Documentation : Beginner’s Guide et location
Suite : Sites virtuels