Skip to content

Nginx Aide-mémoire

Serveur HTTP haute performance et reverse proxy.

01

Premiers pas

Configuration de base

La config nginx utilise une structure de blocs hiérarchique. worker_processes règle le nombre de processus. Le bloc http contient les blocs server, qui contiennent les blocs location. Testez toujours avec nginx -t avant de recharger.

nginx
# /etc/nginx/nginx.conf
worker_processes auto;

events {
    worker_connections 1024;
}

http {
    server {
        listen 80;
        server_name example.com;

        location / {
            root /var/www/html;
            index index.html;
        }
    }
}

# Test config: nginx -t
# Reload: nginx -s reload
# Start: systemctl start nginx

Directives et contextes

Les contextes s'imbriquent : main > events/http/mail > server > location. Les directives simples finissent par un point-virgule ; les directives de bloc utilisent des accolades. Certaines directives ne sont valides que dans des contextes précis.

nginx
# Contexts are hierarchical blocks
# Global context (main) - outside any block
user nginx;
worker_processes auto;

# events context
events {
    worker_connections 1024;
}

# http context
http {
    # server context
    server {
        listen 80;
        # location context
        location / {
            root /var/www/html;
        }
    }
}

# Directives: simple (name value;) or block (name { ... })

Tester et recharger

nginx -t vérifie la syntaxe ET tente d'ouvrir les fichiers référencés (certs, logs). Lancez-le toujours avant un reload. reload envoie SIGHUP — les workers terminent les requêtes en cours puis rechargent. restart cause un court arrêt de service.

nginx
# test configuration for syntax errors
nginx -t

# test and print full config
nginx -T

# reload config without dropping connections
nginx -s reload

# stop gracefully (finishes current requests)
nginx -s quit

# stop immediately
nginx -s stop

# reopen log files (after log rotation)
nginx -s reopen

# systemd alternative
systemctl reload nginx
systemctl restart nginx

Contexte main vs HTTP

worker_processes et events vivent dans le contexte main. Routage, proxying, caching et blocs server vivent dans http. SSL, logging et gzip peuvent se régler dans http et être hérités par server/location.

nginx
# main context - global settings
user nginx;
worker_processes auto;
worker_rlimit_nofile 65535;
pid /var/run/nginx.pid;

events {
    worker_connections 4096;
}

http {
    # all HTTP-related config lives here
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    sendfile      on;
    keepalive_timeout 65;

    include /etc/nginx/conf.d/*.conf;
}

Fichiers include

Les includes gardent la config modulaire. Le glob conf.d (*.conf) est la convention moderne. sites-enabled avec des symlinks est le schéma Debian/Ubuntu. mime.types mappe les extensions de fichiers aux Content-Type.

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

# /etc/nginx/conf.d/default.conf
server {
    listen 80;
    server_name example.com;
    root /var/www/html;
}

# Disable a site: remove the file from sites-enabled/
# Available sites kept in sites-available/, symlinked into enabled/

Opérations en ligne de commande

nginx -V montre les options de compilation, dont les modules intégrés. -g règle des directives qui surchargent la config. -c sert à tester des configs alternatives sans toucher à la valeur par défaut.

nginx
# start nginx (if not managed by systemd)
nginx

# specify a custom config file
nginx -c /path/to/nginx.conf

# set a global directive from command line
nginx -g "worker_processes 4;"

# test config
nginx -t

# print version and build configuration
nginx -V

# send signal to master process
nginx -s reload
nginx -s stop
02

Blocs server

Bloc server de base

Un bloc server définit un hôte virtuel. listen règle le port. server_name matche l'en-tête Host. root fixe la racine documentaire. index précise quels fichiers servir pour les requêtes de répertoire.

nginx
server {
    listen 80;
    server_name example.com www.example.com;
    root /var/www/example;
    index index.html index.htm;

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

Noms de serveur multiples

Nginx matche server_name d'abord exactement, puis wildcard (*.foo.com), puis regex. Le premier bloc server correspondant traite la requête. Utilisez des blocs séparés pour différentes apps sur le même port.

nginx
server {
    listen 80;
    server_name example.com www.example.com;
    # ...
}

server {
    listen 80;
    server_name api.example.com;
    # ...
}

# Wildcard: matches any single-level subdomain
server_name *.example.com;

# Regex (starts with ~)
server_name ~^www\d+\.example\.com$;

Serveur par défaut

default_server traite les requêtes dont l'en-tête Host ne matche aucun server_name. L'underscore est une convention (nom d'hôte invalide, ne matche jamais un vrai trafic). return 444 ferme la connexion sans réponse.

nginx
# mark a server block as default for the port
server {
    listen 80 default_server;
    server_name _;
    return 444;  # drop connection (no response)
}

# handles all requests that don't match another server_name
# _ is an invalid hostname, used as catch-all convention
# useful to block requests with no matching Host header

Directive listen

listen peut se lier à une adresse précise, IPv6, socket UNIX, ou définir le default_server. Le paramètre ssl active TLS pour cet écouteur. Plusieurs directives listen sont autorisées dans un même bloc server.

nginx
# listen on port 80
listen 80;

# IPv6
listen [::]:80;

# HTTPS (ssl flag)
listen 443 ssl;
listen [::]:443 ssl;

# specific address
listen 127.0.0.1:8080;

# default server for this port
listen 80 default_server;

# listen on UNIX socket
listen unix:/var/run/nginx.sock;

Matching des noms de serveur

La priorité de matching est exact > wildcard-de-tête > wildcard-de-fin > regex. Les regex sont vérifiées dans l'ordre de la config, donc la première gagne. Augmentez la taille des hash buckets si les noms de serveur sont longs ou nombreux.

nginx
# Order of precedence (highest to lowest):
# 1. Exact name: example.com
# 2. Longest wildcard starting with *: *.example.com
# 3. Longest wildcard ending with *: www.*
# 4. First matching regex (in config order): ~^www\d+\.

# If nothing matches, the default_server handles it

# Tune hash sizes for many server names
http {
    server_names_hash_bucket_size 64;
    server_names_hash_max_size 512;
}

Serveur catch-all

Un catch-all empêche les requêtes avec des en-têtes Host arbitraires d'atteindre vos apps. return 301 redirige vers un hôte connu. return 444 coupe la connexion, utile contre les scanners qui frappent directement votre IP.

nginx
# catch all requests regardless of host header
server {
    listen 80 default_server;
    server_name _;  # invalid name, never matches real host

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

# or drop the connection silently
server {
    listen 80 default_server;
    server_name _;
    return 444;
}

# redirect unknown subdomains to main site
server {
    listen 80 default_server;
    return 301 https://example.com;
}
03

Blocs location

Modificateurs de location

Les modificateurs changent le comportement de matching : = (exact), ^~ (préfixe, saute la regex), ~ (regex sensible à la casse), ~* (regex insensible), aucun (préfixe). La regex convient mieux aux extensions de fichiers ; le préfixe aux arbres de chemins.

nginx
# exact match - fastest, stops search if matched
location = /favicon.ico {
    log_not_found off;
}

# prefix match with ^~ - skips regex if longest prefix matches
location ^~ /static/ {
    root /var/www;
}

# case-sensitive regex
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php-fpm.sock;
}

# case-insensitive regex
location ~* \.(jpg|jpeg|png|gif|ico)$ {
    expires 30d;
}

# prefix match (no modifier)
location / {
    try_files $uri $uri/ /index.php;
}

Priorité des locations

Nginx évalue d'abord l'exact (=), puis les matchs de préfixe (le plus long gagne), puis les regex dans l'ordre de la config. ^~ fait qu'un match de préfixe saute l'évaluation des regex. Comprendre cet ordre prévient les surprises avec des locations qui se chevauchent.

nginx
# Priority order (highest to lowest):
# 1. =     exact match
# 2. ^~    prefix match (skips regex if matched)
# 3. ~ ~*  regex (first match in config order)
# 4. (none) prefix match (longest wins)

location = /api {
    # exact, highest priority
}

location ^~ /assets/ {
    # prefix, beats regex
}

location ~ \.php$ {
    # regex
}

location /api/ {
    # prefix, lowest of these
}

Root vs Alias

root ajoute l'URI à sa valeur ; alias remplace le préfixe matché. Utilisez root quand la location mappe un sous-répertoire d'un arbre. Utilisez alias quand le chemin d'URI diffère du chemin filesystem. alias avec regex exige une capture $1.

nginx
# root: appends the full URI to the path
# request /img/cat.png -> /var/www/img/cat.png
location /img/ {
    root /var/www;
}

# alias: replaces the matched location part
# request /img/cat.png -> /data/images/cat.png
location /img/ {
    alias /data/images/;
}

# alias with regex requires capturing the path
location ~ ^/img/(.*)$ {
    alias /data/images/$1;
}

try_files

try_files vérifie chaque argument dans l'ordre ; le dernier est le fallback (sans vérification de fichier). $uri vérifie le fichier, $uri/ le répertoire. Le fallback peut être un URI, =code, ou @nommé. Indispensable pour les SPAs et le routage de CMS.

nginx
# try files in order, fall back to last option
location / {
    try_files $uri $uri/ /index.html;
}

# serve index.php if file/dir not found (pretty URLs)
location / {
    try_files $uri $uri/ /index.php?$query_string;
}

# return 404 if nothing matches
location / {
    try_files $uri =404;
}

# named location as fallback
location / {
    try_files $uri $uri/ @drupal;
}

Locations nommées

Les locations nommées (@nom) sont internes uniquement — jamais matchées directement par un URI de requête. Ce sont des cibles pour try_files, error_page et rewrite. Idéal pour partager un bloc de config (comme un handler de fallback) entre plusieurs locations.

nginx
# named locations start with @, can't be reached externally
# used as try_files fallback or rewrite target

location / {
    try_files $uri $uri/ @app;
}

location @app {
    fastcgi_pass unix:/run/php.sock;
    # ... fastcgi config
}

# useful for organizing common error logic
location @error_page {
    return 500 "Internal Server Error";
}

# can also be used with error_page
error_page 404 @fallback;
location @fallback {
    proxy_pass http://backend;
}

Locations imbriquées

Les locations peuvent s'imbriquer. Les locations internes héritent et peuvent surcharger les directives des externes. Utile pour traiter spécialement un chemin dans un préfixe plus large (ex. une taille de corps plus grande pour les uploads, ou servir des fichiers statiques depuis un sous-chemin).

nginx
location /api {
    # /api/users, /api/posts handled here
    proxy_pass http://backend;

    location /api/upload {
        # override for upload endpoint
        client_max_body_size 50M;
        proxy_pass http://upload_backend;
    }

    location ~ ^/api/static/(.*)$ {
        # regex inside prefix location
        root /var/www;
    }
}
04

Reverse proxy

Proxy pass de base

proxy_pass transmet les requêtes à un serveur upstream. Un slash final sur proxy_pass fait remplacer le préfixe de location matché. Sans slash final, l'URI d'origine passe inchangé.

nginx
server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://localhost:3000;
    }
}

# proxy_pass with URI replacement (trailing slash matters)
location /api/ {
    proxy_pass http://backend/;  # /api/foo -> /foo
}

# without trailing slash, URI is preserved
location /api/ {
    proxy_pass http://backend;   # /api/foo -> /api/foo
}

En-têtes de proxy

Par défaut nginx ne transmet pas l'IP client ni l'hôte d'origine. Régler X-Real-IP et X-Forwarded-For permet au backend d'identifier le vrai client. X-Forwarded-Proto lui indique le schéma d'origine, critique pour la logique de redirection HTTPS.

nginx
location / {
    proxy_pass http://backend;

    # preserve original host
    proxy_set_header Host $host;

    # real client IP (not nginx's)
    proxy_set_header X-Real-IP $remote_addr;

    # forwarded-for chain
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    # scheme (http or https)
    proxy_set_header X-Forwarded-Proto $scheme;

    # original host
    proxy_set_header X-Forwarded-Host $host;
}

Proxy upstream

Un bloc upstream définit un pool de serveurs nommé que proxy_pass peut référencer. Cela permet l'équilibrage de charge, les health checks et les connexions keepalive. Les variables upstream servent à logger quel backend a traité chaque requête.

nginx
# define a named pool of backend servers
upstream backend {
    server 10.0.0.1:8080;
    server 10.0.0.2:8080;
    server 10.0.0.3:8080;
}

server {
    listen 80;

    location / {
        proxy_pass http://backend;
    }
}

# useful upstream variables:
# $upstream_addr, $upstream_status,
# $upstream_response_time, $upstream_cache_status

Timeouts de proxy

proxy_connect_timeout est la limite du handshake TCP ; les timeouts read/send s'appliquent aux périodes d'inactivité pendant le transfert. Augmentez read_timeout pour les endpoints lents (exports, inférence IA). upstream keepalive réutilise les connexions pour réduire la latence.

nginx
location / {
    proxy_pass http://backend;

    # connect timeout (TCP handshake to upstream)
    proxy_connect_timeout 5s;

    # time between reads from upstream (response)
    proxy_read_timeout 60s;

    # time between writes to upstream (request body)
    proxy_send_timeout 60s;

    # for slow backends (large uploads/downloads)
    proxy_read_timeout 300s;
}

# keepalive connections to upstream
upstream backend {
    server 10.0.0.1:8080;
    keepalive 32;
}

Buffering du proxy

Le buffering stocke la réponse upstream en mémoire/disque avant de l'envoyer au client — efficace pour les clients lents mais casse le streaming. Désactivez-le pour SSE, WebSocket ou streaming chunked. buffer_size est la première partie (en-têtes) ; buffers accueillent le reste.

nginx
location / {
    proxy_pass http://backend;

    # enable buffering (default on)
    proxy_buffering on;
    proxy_buffer_size 4k;
    proxy_buffers 8 4k;

    # busy buffers during streaming
    proxy_busy_buffers_size 16k;

    # disable for streaming/SSE
    proxy_buffering off;
    proxy_cache off;
}

# Server-Sent Events or streaming responses
location /events {
    proxy_pass http://backend;
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding on;
}

Upgrade WebSocket

WebSocket exige HTTP/1.1 plus les en-têtes Upgrade et Connection. Le bloc map convertit l'en-tête Upgrade en valeur Connection correcte (upgrade vs close). Un proxy_read_timeout long empêche la fermeture des WebSockets inactifs.

nginx
# Map the Upgrade header to a Connection value
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;

    location /ws {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        # keepalive for long-lived connections
        proxy_read_timeout 3600s;
    }
}
05

Équilibrage de charge

Bloc upstream

Un bloc upstream définit les serveurs backend. L'équilibrage par défaut est le round-robin. max_fails et fail_timeout configurent les health checks passifs : après max_fails échecs dans fail_timeout, le serveur est marqué down pendant fail_timeout secondes.

nginx
upstream backend {
    server backend1.example.com weight=5;
    server backend2.example.com;
    server backend3.example.com max_fails=3 fail_timeout=30s;
}

server {
    location / {
        proxy_pass http://backend;
    }
}

# default algorithm: round-robin
# max_fails: failed attempts before marking server down
# fail_timeout: window for counting fails AND downtime duration

Méthodes d'équilibrage

round-robin distribue uniformément ; least_conn envoie au serveur le moins chargé ; ip_hash garde un client sur le même serveur (sessions collantes par IP) ; hash distribue par une clé personnalisée. Le paramètre consistent minimise la redistribution quand des serveurs sont ajoutés/retirés.

nginx
# round-robin (default) - even distribution
upstream backend {
    server s1.example.com;
    server s2.example.com;
}

# least connections - fewest active connections
upstream backend {
    least_conn;
    server s1.example.com;
    server s2.example.com;
}

# ip_hash - sticky by client IP (session persistence)
upstream backend {
    ip_hash;
    server s1.example.com;
    server s2.example.com;
}

# generic hash (key-based, e.g., by URI or header)
upstream backend {
    hash $request_uri consistent;
    server s1.example.com;
    server s2.example.com;
}

Round robin pondéré

weight contrôle la répartition du trafic proportionnellement. Le poids par défaut est 1. Donnez des poids plus élevés aux serveurs plus puissants pour qu'ils prennent une part plus grande. Les poids marchent avec round-robin, least_conn et ip_hash.

nginx
upstream backend {
    server s1.example.com weight=3;  # 3x traffic
    server s2.example.com weight=2;  # 2x traffic
    server s3.example.com weight=1;  # 1x traffic (default)
}

# total weight = 6
# s1 gets 3/6 = 50%, s2 gets 2/6 = 33%, s3 gets 1/6 = 17%

# useful when servers have different capacity
# e.g., a 4-core server gets weight=4, a 2-core gets weight=2

Health checks

Le nginx open-source utilise des health checks passifs (max_fails/fail_timeout) fondés sur les échecs réels de requêtes. NGINX Plus ajoute des health checks actifs qui sondent périodiquement un URI. Un serveur doit passer 'passes' vérifications consécutives pour être re-marqué sain.

nginx
upstream backend {
    server s1.example.com max_fails=3 fail_timeout=30s;
    server s2.example.com max_fails=3 fail_timeout=30s;

    # passive health check (default behavior):
    # 3 failures within 30s marks the server down
    # it stays down for fail_timeout (30s) before retry
}

# NGINX Plus active health check
upstream backend {
    server s1.example.com;
    server s2.example.com;
    health_check interval=10s fails=3 passes=2;
    health_check uri=/health;
}

Persistance de session

ip_hash fournit des sessions collantes par IP client mais casse si l'IP change (réseaux mobiles). La directive hash avec consistent offre une redistribution minimale des clés quand le pool change. sticky cookie (Plus) pose un cookie pour épingler un client à un serveur.

nginx
# ip_hash: routes by client IP (uses first 3 IPv4 octets)
upstream backend {
    ip_hash;
    server s1.example.com:8080;
    server s2.example.com:8080;
}

# sticky cookie (NGINX Plus only)
upstream backend {
    sticky cookie srv_id expires=1h domain=.example.com path=/;
    server s1.example.com;
    server s2.example.com;
}

# hash with consistent parameter for minimal redistribution
upstream backend {
    hash $http_x_session_id consistent;
    server s1.example.com;
    server s2.example.com;
}

Serveurs backup

Marqués du paramètre backup, ces serveurs ne reçoivent du trafic que si tous les serveurs primaires échouent. Motif courant : les primaires servent l'app ; un backup sert une page de maintenance statique. Les serveurs backup sont exclus de l'équilibrage normal.

nginx
upstream backend {
    server s1.example.com;
    server s2.example.com;

    # used only when all primaries are down
    server s3.example.com backup;
    server s4.example.com backup;
}

# backup servers receive traffic ONLY when all
# non-backup servers are unavailable
# useful for a maintenance page or DR fallback

upstream backend {
    server primary.example.com;
    server standby.example.com backup;
}
06

Configuration SSL/TLS

Serveur HTTPS de base

Le paramètre ssl sur listen active TLS. ssl_certificate pointe vers la chaîne de certificats (cert serveur + intermédiaires) ; ssl_certificate_key vers la clé privée. Utilisez toujours fullchain.pem pour que les clients puissent vérifier la chaîne.

nginx
server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/ssl/certs/example.com.crt;
    ssl_certificate_key /etc/ssl/private/example.com.key;

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

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

Mise en place du certificat SSL

Let's Encrypt stocke les certs sous /etc/letsencrypt/live/<domaine>/. fullchain.pem inclut les intermédiaires ; privkey.pem est la clé privée. nginx supporte plusieurs types de certs par serveur, en choisissant selon la capacité du client.

nginx
# Let's Encrypt paths
ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

# multiple cert types (RSA + ECDSA) on one server
server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/ssl/example.com.rsa.crt;
    ssl_certificate_key /etc/ssl/example.com.rsa.key;

    ssl_certificate     /etc/ssl/example.com.ecdsa.crt;
    ssl_certificate_key /etc/ssl/example.com.ecdsa.key;
}

Redirection HTTP vers HTTPS

Le motif le plus propre est un serveur dédié au port 80 qui redirige. $host préserve le nom d'hôte d'origine. Utiliser if ($scheme) dans un bloc combiné marche mais l'approche à serveur séparé est préférée et évite les pièges du « if is evil ».

nginx
# redirect all HTTP traffic to HTTPS
server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

# single server block handling both
server {
    listen 80;
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/ssl/example.com.crt;
    ssl_certificate_key /etc/ssl/example.com.key;

    if ($scheme != "https") {
        return 301 https://$host$request_uri;
    }
}

Protocoles et ciphers SSL

Désactivez les vieux protocoles (SSLv3, TLSv1.0/1.1). TLS 1.3 est le plus rapide et le plus sûr. Utilisez le Mozilla SSL Configuration Generator pour un profil testé. Le cache shared:SSL accélère la reprise de session entre workers.

nginx
server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/ssl/example.com.crt;
    ssl_certificate_key /etc/ssl/example.com.key;

    # modern configuration (Mozilla SSL Config Generator)
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # session settings
    ssl_session_tickets off;
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:50m;
}

HSTS

HSTS demande aux navigateurs d'utiliser toujours HTTPS pour le domaine, bloquant les attaques SSL-stripping. max-age est en secondes (31536000 = 1 an). includeSubDomains couvre tous les sous-domaines. preload inscrit le site dans une liste intégrée aux navigateurs — quasi irréversible, à utiliser avec soin.

nginx
server {
    listen 443 ssl;
    server_name example.com;

    # HSTS: force HTTPS for 1 year (include subdomains)
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # preload list (be very careful — requires permanent HTTPS)
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
}

# Preload commits your domain to a browser-baked HTTPS-only list.
# Only enable preload after verifying all subdomains work on HTTPS.

OCSP Stapling

L'OCSP stapling permet à nginx d'aller chercher et servir le statut de révocation du certificat, épargnant au client un aller-retour vers le responder OCSP. ssl_trusted_certificate est nécessaire pour vérifier la réponse OCSP. Un resolver est requis pour que nginx atteigne le serveur OCSP.

nginx
server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/ssl/example.com/fullchain.pem;
    ssl_certificate_key /etc/ssl/example.com/privkey.pem;

    ssl_stapling on;
    ssl_stapling_verify on;

    # trust chain for verification
    ssl_trusted_certificate /etc/ssl/example.com/chain.pem;

    # DNS resolver needed for OCSP requests
    resolver 8.8.8.8 8.8.4.4 valid=300s;
    resolver_timeout 5s;
}
07

Service de fichiers statiques

Servir des fichiers statiques

root définit la racine documentaire ; nginx mappe l'URI de requête vers un chemin de fichier. try_files vérifie le fichier, puis le répertoire, puis retourne 404. Régler root au niveau server fait hériter toutes les locations, mais on peut surcharger par location.

nginx
server {
    listen 80;
    server_name example.com;
    root /var/www/html;

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

# root set at server level is inherited by all locations
# request /images/logo.png -> /var/www/html/images/logo.png
# request /css/style.css   -> /var/www/html/css/style.css

Directive index

index liste les fichiers à essayer quand la requête vise un répertoire. Le premier fichier existant est servi. Si aucun n'existe et autoindex est off, nginx retourne 403. L'ordre compte — listez d'abord les fichiers préférés.

nginx
server {
    listen 80;
    root /var/www/html;

    # try these files in order when request targets a directory
    index index.html index.htm index.php;

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

# request / -> tries /var/www/html/index.html, then index.htm
# request /about/ -> tries /var/www/html/about/index.html
# if no index file found and autoindex off -> 403 Forbidden

try_files pour SPA

Les SPAs routent côté client, donc les chemins inconnus doivent servir index.html. try_files $uri $uri/ /index.html fait exactement cela. Cachez les assets hashés un an avec immutable, puisque leurs noms adressés par contenu garantissent une nouvelle URL au changement de contenu.

nginx
# Single Page Application (React, Vue, Angular)
server {
    listen 80;
    root /var/www/spa;

    location / {
        # serve static files, fall back to index.html for client routing
        try_files $uri $uri/ /index.html;
    }

    # cache static assets aggressively (filename usually hashed)
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Autoindex (liste de répertoire)

autoindex génère une liste HTML du répertoire. Utile pour les sites de téléchargement. Désactivez exact_size pour la lisibilité et activez localtime pour des timestamps corrects. N'activez jamais sur des répertoires à fichiers sensibles — associez toujours un contrôle d'accès.

nginx
location /files/ {
    autoindex on;
    autoindex_exact_size off;  # human-readable sizes (KB, MB)
    autoindex_localtime on;    # show local time instead of UTC
    root /var/www;
}

# /files/        -> directory listing
# /files/doc.pdf -> downloads the file
# /files/sub/    -> listing of subdirectory

# disable for security on sensitive directories
location /private/ {
    autoindex off;
    deny all;
}

En-têtes Expire

expires règle le max-age de Cache-Control. immutable dit aux navigateurs que le fichier ne change jamais (saute la revalidation). Pour les assets hashés (fichier.abc123.js), 1y + immutable est idéal. Le HTML doit toujours revalider pour que les utilisateurs reçoivent les mises à jour immédiatement.

nginx
# cache static assets for a year
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
    access_log off;
}

# never cache HTML (always revalidate)
location ~* \.html$ {
    add_header Cache-Control "no-cache, no-store, must-revalidate";
}

# short cache for API responses
location /api/ {
    add_header Cache-Control "no-cache";
}

Désactiver le log pour le statique

Les requêtes d'assets statiques et de favicon/robots encombrent les access logs. access_log off arrête le logging ; log_not_found off supprime les entrées 404 du log. Cela garde les logs concentrés sur le trafic utile et réduit l'I/O disque sur les sites très fréquentés.

nginx
# don't log requests for static assets
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
    access_log off;
    log_not_found off;
    expires 1y;
}

# don't log favicon requests (often 404 from browsers)
location = /favicon.ico {
    log_not_found off;
    access_log off;
}

# don't log robots.txt
location = /robots.txt {
    log_not_found off;
    access_log off;
}
08

Compression Gzip

Activer Gzip

gzip compresse les réponses, réduisant la bande passante. gzip_vary ajoute 'Vary: Accept-Encoding' pour les caches. gzip_proxied any compresse aussi pour les requêtes proxifiées. comp_level 6 équilibre CPU et taille. min_length 256 saute les réponses minuscules (l'overhead dépasse le gain).

nginx
http {
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_min_length 256;
    gzip_types
        text/plain
        text/css
        text/xml
        application/json
        application/javascript
        application/xml+rss
        application/atom+xml
        image/svg+xml;
}

Types Gzip

gzip_types liste les types MIME à compresser. text/html est toujours compressé par défaut. Ne compressez pas les formats binaires déjà compressés (images, vidéo, archives) — vous gaspillez du CPU sans réduction de taille et pouvez même agrandir la sortie.

nginx
http {
    gzip on;
    gzip_types
        text/plain
        text/css
        text/xml
        text/javascript
        application/javascript
        application/x-javascript
        application/json
        application/xml
        application/xml+rss
        application/rss+xml
        application/atom+xml
        image/svg+xml
        font/ttf
        font/otf
        application/vnd.ms-fontobject;

    # text/html is always compressed (implicitly, cannot disable)
    # DON'T compress already-compressed: jpg, png, gif, mp4, zip, gz
}

Niveau de compression Gzip

comp_level échange CPU contre compression. 6 est le point idéal — 9 consomme bien plus de CPU pour <2 % de sortie plus petite. min_length évite de compresser des réponses minuscules où l'overhead d'en-tête gzip dépasse le gain. gzip_disable exclut le vieil IE6 au support gzip défaillant.

nginx
http {
    gzip on;
    gzip_comp_level 6;  # 1-9, higher = more compression, more CPU

    # level 1: fast, low compression
    # level 6: good balance (recommended default)
    # level 9: slow, marginal size gain

    # minimum response size to compress (bytes)
    gzip_min_length 256;

    # disable gzip for old browsers
    gzip_disable "MSIE [1-6]\.";
}

Gzip statique

gzip_static sert des fichiers .gz préconstruits, éliminant le coût CPU de compression à l'exécution. L'étape de build crée les .gz à côté des originaux. nginx sert le .gz aux clients envoyant Accept-Encoding: gzip, l'original aux autres. Idéal pour les pipelines d'assets statiques.

nginx
# serve pre-compressed .gz files (no runtime compression cost)
# requires ngx_http_gzip_static_module

location / {
    gzip_static on;
    # on:     serve .gz if it exists
    # always: serve .gz even without Accept-Encoding header

    root /var/www/html;
}

# pre-compress files at build time:
# find /var/www/html -type f ( -name "*.css" -o -name "*.js" \
#   -o -name "*.html" ) -exec gzip -k -9 {} \;
# creates file.css.gz, file.js.gz alongside the originals

Brotli

Brotli surpasse gzip pour le contenu textuel, surtout à haut niveau de compression. Il exige le module tiers ngx_brotli. brotli_static sert des fichiers .br préconstruits. Les navigateurs modernes annoncent 'br' dans Accept-Encoding, donc nginx choisit le meilleur disponible.

nginx
# requires ngx_brotli module (not built-in)
http {
    brotli on;
    brotli_comp_level 6;
    brotli_types
        text/plain
        text/css
        application/javascript
        application/json
        image/svg+xml;

    # serve pre-compressed .br files
    brotli_static on;
}

# Brotli typically 10-20% smaller than gzip for text
# supported by all modern browsers (not IE)
# nginx can serve both .br and .gz; picks based on Accept-Encoding

Gzip pour le proxifié

Par défaut nginx ne compresse pas les réponses proxifiées (pour éviter de recompresser des upstreams déjà compressés). gzip_proxied any l'active pour toutes les requêtes proxifiées. gzip_vary garantit que les caches stockent des versions séparées pour clients compressés/non compressés.

nginx
http {
    gzip on;
    gzip_proxied any;
    # gzip_proxied controls compression for proxied requests:
    # off:           never compress proxied requests
    # expired:       compress if response has Expires header
    # no-cache:      compress if Cache-Control: no-cache
    # no-store:      compress if Cache-Control: no-store
    # private:       compress if Cache-Control: private
    # no_last_modified: compress if no Last-Modified header
    # no_etag:       compress if no ETag header
    # auth:          compress if Authorization header present
    # any:           compress all proxied requests

    gzip_vary on;  # add "Vary: Accept-Encoding" header
}
09

Cache

Cache de proxy

proxy_cache stocke les réponses upstream sur disque. keys_zone définit une zone de mémoire partagée pour les clés de cache (10m ≈ 80 000 clés). max_size limite l'usage disque ; inactive retire les entrées non accédées pendant ce délai. use_temp_path=off écrit directement dans le cache pour la vitesse.

nginx
http {
    # define cache zone on disk
    proxy_cache_path /var/cache/nginx levels=1:2
        keys_zone=api_cache:10m
        max_size=1g
        inactive=60m
        use_temp_path=off;

    server {
        location /api/ {
            proxy_pass http://backend;
            proxy_cache api_cache;
            proxy_cache_valid 200 10m;
            proxy_cache_valid 404 1m;
        }
    }
}

Zone de cache

levels=1:2 crée un arbre de répertoires à deux niveaux depuis le hash MD5 de la clé de cache pour éviter trop de fichiers dans un même répertoire. Des zones séparées par type de contenu permettent de régler max_size et inactive indépendamment — statique caché longtemps, API caché brièvement.

nginx
http {
    proxy_cache_path /var/cache/nginx
        levels=1:2              # directory hierarchy depth
        keys_zone=my_cache:10m  # zone name + shared memory size
        max_size=1g             # max disk size for cache
        inactive=60m            # remove if not accessed in 60min
        use_temp_path=off;      # write directly (faster, no temp copy)

    # multiple zones for different content types
    proxy_cache_path /var/cache/static levels=1:2
        keys_zone=static:10m max_size=500m inactive=24h;
    proxy_cache_path /var/cache/api levels=1:2
        keys_zone=api:10m max_size=200m inactive=10m;
}

Clé de cache

La clé de cache détermine l'unicité du cache. La clé par défaut peut causer des collisions entre hôtes virtuels — incluez $host. Pour du contenu par utilisateur, incluez un identifiant. proxy_cache_bypass saute le cache (stocke quand même) ; proxy_no_cache ne stocke pas la réponse.

nginx
location / {
    proxy_pass http://backend;
    proxy_cache api_cache;

    # default key: $scheme$proxy_host$request_uri
    proxy_cache_key "$scheme$request_method$host$request_uri";

    # include user-specific data to avoid cross-user leaks
    proxy_cache_key "$scheme$host$request_uri$http_x_user_id";

    # bypass cache for authenticated users
    proxy_cache_bypass $http_authorization;
    proxy_no_cache $http_authorization;
}

Validité du cache

proxy_cache_valid règle des TTL par code de statut. 0s ou l'omission d'un statut empêche de le cacher. proxy_cache_lock sérialise les cache misses concurrents pour la même clé — une seule requête frappe l'upstream ; les autres attendent la réponse cachée.

nginx
location / {
    proxy_pass http://backend;
    proxy_cache api_cache;

    # cache by response status code
    proxy_cache_valid 200 302 10m;
    proxy_cache_valid 404 1m;
    proxy_cache_valid 500 502 503 504 0s;  # don't cache errors

    # fallback for any other status
    proxy_cache_valid any 1m;

    # cache lock: collapse concurrent misses into one upstream call
    proxy_cache_lock on;
    proxy_cache_lock_timeout 5s;
}

Contourner le cache

proxy_cache_bypass saute la lecture du cache (va à l'upstream) mais peut encore stocker la réponse. proxy_no_cache saute le stockage. L'en-tête X-Cache-Status est précieux pour le débogage — HIT signifie servi du cache, MISS signifie allé chercher à l'upstream.

nginx
location / {
    proxy_pass http://backend;
    proxy_cache api_cache;

    # bypass cache (always go to upstream)
    proxy_cache_bypass $http_authorization $arg_nocache;

    # don't store in cache
    proxy_no_cache $http_authorization;

    # add header showing cache status for debugging
    add_header X-Cache-Status $upstream_cache_status;
}

# $upstream_cache_status values:
# MISS, BYPASS, EXPIRED, STALE, UPDATING, REVALIDATED, HIT

Cache navigateur

Le cache navigateur réduit la latence des visites répétées. immutable saute entièrement la revalidation (sûr seulement pour des noms de fichiers adressés par contenu). no-cache signifie revalider à chaque fois (autorise quand même le GET conditionnel). no-store signifie ne jamais stocker. Associez des ETags pour des réponses 304 efficaces.

nginx
# cache static assets in the browser
location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff2?)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

# HTML - revalidate always
location ~* \.html$ {
    add_header Cache-Control "no-cache, must-revalidate";
    etag on;
}

# API responses - never cache
location /api/ {
    add_header Cache-Control "no-store";
}

# public:    any cache (browser, CDN) may store
# private:   only the browser may store
# immutable: file never changes, skip revalidation
# no-store:  never cache
10

Réécriture d'URL

Directive return

return est le moyen le plus simple de rediriger ou répondre. Il arrête le traitement immédiatement. Utilisez 301 pour permanent, 302 pour temporaire. On peut retourner un code de statut avec un corps (200, 418) ou une redirection vers une URL. Préférez return à rewrite pour les redirections.

nginx
# simplest redirect/rewrite - return stops processing
server {
    location /old {
        return 301 /new;
    }

    location /external {
        return 301 https://example.com$request_uri;
    }

    location /api {
        return 200 "OK\n";
    }

    location /teapot {
        return 418 "I'm a teapot";
    }
}

# return is preferred over rewrite for simple redirects

Directive rewrite

rewrite matche l'URI contre une regex et le remplace. last réévalue le matching des locations avec le nouvel URI (comme repartir de zéro). break arrête la réécriture mais reste dans la location courante. redirect/permanent envoient une redirection au navigateur.

nginx
# rewrite regex replacement [flag]
server {
    # rewrite /old/* to /new/* preserving the captured part
    rewrite ^/old/(.*)$ /new/$1 permanent;

    # rewrite old blog URLs to new structure
    rewrite ^/blog/(\d{4})/(\d{2})/(.*)$ /articles/$1/$2/$3 last;

    # capture with named groups
    rewrite ^/download/(.*)$ /assets/$1 last;
}

# flags:
# last:      re-search locations with the new URI
# break:     stop rewrite, continue in current location
# redirect:  302 temporary redirect
# permanent: 301 permanent redirect

Flags de rewrite

last vs break est la partie la plus confuse. last relance la recherche de location (utile quand la réécriture vise une autre location). break arrête la réécriture mais reste (utile quand elle ajuste juste un chemin interne). redirect/permanent changent l'URL du navigateur.

nginx
location / {
    # last: restart location matching with new URI
    rewrite ^/api/(.*)$ /backend/$1 last;

    # break: stop processing rewrites, stay in current location
    rewrite ^/static/(.*)$ /assets/$1 break;

    # redirect: 302 temporary redirect (browser URL changes)
    rewrite ^/old/(.*)$ /new/$1 redirect;

    # permanent: 301 permanent redirect (browser URL changes)
    rewrite ^/old/(.*)$ /new/$1 permanent;
}

# avoid rewrite inside if blocks - use location + try_files instead

Captures nommées

Les captures nommées (?<nom>motif) créent des variables ($nom) plus claires que les positionnelles $1, $2. Elles marchent dans la regex de location et dans rewrite. Les valeurs capturées sont disponibles dans proxy_pass, fastcgi_param, add_header et log_format de cette location.

nginx
# named captures in regex locations
location ~ ^/users/(?<username>[a-z]+)/?$ {
    proxy_pass http://backend/users/$username;
}

# named captures in rewrite
location / {
    rewrite ^/articles/(?<year>\d{4})/(?<slug>[a-z-]+)/?$
        /blog?year=$year&slug=$slug last;
}

# named captures become variables: $year, $slug, $username
# accessible in proxy_pass, fastcgi_pass, headers, etc.
# safer than $1, $2 positional captures for readability

Directive map

map construit une table de correspondance d'une variable à une autre, évaluée paresseusement. Bien plus efficace et lisible que des chaînes de if. La branche default gère les valeurs non matchées. Les matchs regex (préfixés de ~) sont vérifiés dans l'ordre.

nginx
# map creates a new variable based on another variable's value
map $http_host $backend {
    default            "http://default.backend";
    "a.com"            "http://a.backend";
    "b.com"            "http://b.backend";
    "~^.*\.app\.com$" "http://app.backend";
}

server {
    server_name a.com b.com;
    location / {
        proxy_pass $backend;
    }
}

# map is evaluated lazily and cached per request
# more efficient than if/else chains

Directive if (prudence)

if a un comportement surprenant dans les blocs location — il peut réécrire les configs de façon imprévisible. Les seuls usages universellement sûrs sont return et rewrite. Pour tester l'existence d'un fichier, utilisez try_files. Pour une logique complexe, utilisez map ou des blocs location séparés. Voir le wiki : « If Is Evil ».

nginx
# "if is evil" — use sparingly! Only safe for:
# return / rewrite, and with these checks:
#   -f, -d, -e, -x (file/dir/exists/executable)
#   =, !=, ~, ~* (string/regex comparison)

location / {
    if ($request_method = POST) {
        return 405;
    }

    if ($http_user_agent ~* "bot") {
        return 403;
    }

    # BAD: don't do this inside if
    # if (-f $request_filename) { ... }
    # use try_files instead
    try_files $uri $uri/ /index.html;
}
11

Redirection

Redirection permanente (301)

301 signifie « déplacé définitivement » — navigateurs et moteurs de recherche le cachent, donc ne l'utilisez que pour des changements vraiment permanents. Testez d'abord en 302 pour éviter d'enfermer une erreur. Le 301 transmet le capital de liens (SEO) à la nouvelle URL.

nginx
# 301 - permanent redirect (cached by browsers indefinitely)
server {
    listen 80;
    server_name old-domain.com;

    # redirect entire site to a new domain
    return 301 https://new-domain.com$request_uri;
}

location /old-page {
    return 301 /new-page;
}

# 301 caches indefinitely in browsers — test with 302 first!
# Search engines treat 301 as a permanent move and update indexes.

Redirection temporaire (302)

302 transforme POST en GET à la redirection (comportement historique). 307 et 308 préservent la méthode — important pour resoumettre des POST. 303 convertit explicitement en GET (utile après soumission de formulaire pour éviter une double soumission au rafraîchissement). Choisissez selon la préservation ou non de la méthode.

nginx
# 302 - temporary redirect (not cached by default)
location /maintenance {
    return 302 /maintenance.html;
}

# 307 - temporary, preserves HTTP method (POST stays POST)
location /api/v1 {
    return 307 /api/v2;
}

# 308 - permanent, preserves HTTP method
location /api/v1 {
    return 308 /api/v2;
}

# 303 - see other (always uses GET for the new request)
location /form-submit {
    return 303 /success;
}

Rediriger www vers non-www

Choisissez une forme canonique (www ou non-www) et redirigez l'autre. Deux blocs server est le motif le plus propre : le non canonique ne fait que rediriger. $request_uri préserve le chemin et la query string. Appliquez la même logique aux redirections HTTPS.

nginx
# www to non-www
server {
    listen 80;
    server_name www.example.com;
    return 301 https://example.com$request_uri;
}

server {
    listen 80;
    server_name example.com;
    # ... main site config
}

# non-www to www (reverse direction)
server {
    listen 80;
    server_name example.com;
    return 301 https://www.example.com$request_uri;
}

Rediriger HTTP vers HTTPS

$host préserve le nom d'hôte d'origine, donc la redirection marche pour tout server_name. $request_uri préserve le chemin et la query. Pour des ports non standard, ajoutez :port à $host. Un bloc server dédié au port 80 est plus propre que des vérifications if par location.

nginx
server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

# with a non-standard HTTPS port
server {
    listen 8080;
    return 301 https://$host:8443$request_uri;
}

# redirect only a specific path
location /secure {
    if ($scheme = http) {
        return 301 https://$host$request_uri;
    }
}

Rediriger vers un autre domaine

Pour une migration de domaine, $request_uri préserve le chemin complet et la query pour que les liens ne cassent pas. Utilisez rewrite avec une capture quand la structure du chemin change. 301 est correct pour une migration permanente — il transfère le référencement SEO au nouveau domaine.

nginx
# domain migration — preserve all paths
server {
    listen 80;
    server_name old.com www.old.com;
    return 301 https://new.com$request_uri;
}

# preserve path and query string
location /docs/ {
    return 301 https://docs.new.com$request_uri;
}

# with path rewrite using capture groups
location /old-blog/ {
    rewrite ^/old-blog/(.*)$ https://blog.new.com/$1 permanent;
}

Redirection par chemin

Les redirections par chemin servent aux nettoyages d'URL (suppression de slashes finaux, d'extensions) et aux déplacements de contenu. Des locations regex avec captures ($1) permettent une réécriture flexible des chemins. Les redirections selon paramètres de requête utilisent $arg_nom pour lire chaque paramètre.

nginx
# redirect specific paths
location /promo/2023 {
    return 301 /promo/2024;
}

# remove trailing slash
location ~ ^/(.*)/$ {
    return 301 /$1;
}

# remove .html extension
location ~ ^/(.*)\.html$ {
    return 301 /$1;
}

# redirect based on query parameter
location /download {
    if ($arg_version = "1") {
        return 301 /download?v=2;
    }
}
12

FastCGI (PHP-FPM)

Mise en place PHP-FPM

fastcgi_pass envoie les requêtes PHP à PHP-FPM via un socket UNIX (plus rapide, local seulement) ou un port TCP. include fastcgi_params règle les variables CGI standard. SCRIPT_FILENAME dit à PHP quel fichier exécuter — en combinant la racine documentaire avec le chemin du script.

nginx
server {
    listen 80;
    server_name example.com;
    root /var/www/laravel/public;
    index index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        # or: fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

Paramètres FastCGI

fastcgi_params règle les variables d'environnement transmises à PHP. SCRIPT_FILENAME est la plus critique — sans elle, PHP ne trouve pas le script. Des paramètres personnalisés (APP_ENV, DB_HOST) permettent d'injecter de la config sans modifier l'app. PATH_INFO active les URLs propres dans certains frameworks.

nginx
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php-fpm.sock;

    # standard CGI parameters
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO $fastcgi_path_info;

    # custom application parameters
    fastcgi_param APP_ENV production;
    fastcgi_param DB_HOST db.internal;

    # flag for HTTPS (so PHP knows the original scheme)
    fastcgi_param HTTPS $https_flag;
}

Cache FastCGI

fastcgi_cache stocke les réponses PHP, réduisant drastiquement la charge des pages cachables. fastcgi_cache_use_stale sert une réponse cachée périmée si le backend échoue ou timeout — améliore la résilience. Veillez à ne pas cacher du contenu par utilisateur ou authentifié.

nginx
http {
    fastcgi_cache_path /var/cache/nginx/php
        levels=1:2
        keys_zone=phpcache:100m
        max_size=1g
        inactive=60m;

    server {
        location ~ \.php$ {
            fastcgi_pass unix:/run/php/php-fpm.sock;
            include fastcgi_params;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

            fastcgi_cache phpcache;
            fastcgi_cache_valid 200 10m;
            fastcgi_cache_key $scheme$host$request_uri;
            fastcgi_cache_use_stale error timeout invalid_header;
        }
    }
}

Buffers FastCGI

Les buffers accueillent la réponse PHP avant envoi au client. Des buffers trop petits poussent nginx à écrire sur disque (lent) pour les grandes réponses. Si vous voyez des erreurs « upstream sent too big header », augmentez fastcgi_buffer_size. Pour les grosses réponses API, utilisez des buffers plus grands et moins nombreux.

nginx
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php-fpm.sock;

    # buffer settings
    fastcgi_buffering on;
    fastcgi_buffer_size 16k;
    fastcgi_buffers 16 16k;
    fastcgi_busy_buffers_size 32k;

    # for large responses (e.g., PHP generating big JSON)
    fastcgi_buffers 64 16k;
    fastcgi_buffer_size 32k;

    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Timeouts FastCGI

fastcgi_read_timeout est le temps pendant lequel nginx attend la sortie de PHP. Les scripts longs (imports de données, génération de rapports, appels IA) exigent des valeurs plus hautes. Assurez-vous que max_execution_time de PHP est au moins aussi élevé, sinon PHP timeoutera d'abord.

nginx
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php-fpm.sock;

    fastcgi_connect_timeout 5s;
    fastcgi_read_timeout 300s;    # for long-running scripts
    fastcgi_send_timeout 300s;

    # increase for very slow PHP scripts (imports, exports, reports)
    fastcgi_read_timeout 600s;
}

# also adjust max_execution_time in php.ini to match
# otherwise PHP kills the script before nginx times out

try_files avec PHP

try_files $uri $uri/ /index.php?$args est le motif standard des frameworks PHP (WordPress, Laravel, Drupal). Il sert les vrais fichiers/répertoires, sinon route vers index.php avec la query string. $args préserve les paramètres de requête d'origine.

nginx
# WordPress-style pretty URLs
server {
    root /var/www/wordpress;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    # deny access to sensitive files
    location ~* /wp-config.php {
        deny all;
    }
}
13

Proxy WebSocket

Proxy WebSocket

WebSocket exige HTTP/1.1 plus les en-têtes Upgrade et Connection. Le bloc map convertit l'en-tête Upgrade du client en valeur Connection correcte : 'upgrade' pour WebSocket, 'close' pour le HTTP normal. Le read_timeout long garde vivantes les connexions WebSocket inactives.

nginx
# Map the Upgrade header to a Connection value
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name ws.example.com;

    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        proxy_read_timeout 3600s;  # 1 hour
        proxy_send_timeout 3600s;
    }
}

En-têtes Upgrade

HTTP/1.1 est obligatoire pour WebSocket (HTTP/2 gère le multiplexage autrement). Connection peut être codé dur à 'upgrade', mais l'approche par variable map gère aussi les requêtes non WebSocket sur la même location. Passez Host pour que le backend valide l'en-tête Origin.

nginx
location /ws {
    proxy_pass http://backend;

    # HTTP/1.1 is required for the Upgrade mechanism
    proxy_http_version 1.1;

    # pass the Upgrade header through
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    # preserve host for origin checks on the backend
    proxy_set_header Host $host;

    # real client IP
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

Timeout WebSocket

Le proxy_read_timeout par défaut (60s) ferme les connexions WebSocket inactives. Réglez-le haut (86400s = 24 h) pour garder les connexions entre messages. proxy_buffering off garantit que les messages atteignent le client immédiatement plutôt que d'être batchés.

nginx
location /ws {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    # WebSocket connections are long-lived
    # default 60s would close them during idle periods
    proxy_read_timeout 86400s;  # 24 hours
    proxy_send_timeout 86400s;

    # disable buffering for real-time messages
    proxy_buffering off;
}

Proxy Socket.io

Socket.io démarre en long-polling HTTP puis upgrade vers WebSocket si disponible. Les deux transports passent par le même proxy_pass, donc une location suffit. Transmettre X-Forwarded-Proto permet à socket.io de savoir qu'il est derrière HTTPS et de construire les bonnes URLs.

nginx
server {
    listen 80;
    server_name socket.example.com;

    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;

        proxy_read_timeout 86400s;

        # socket.io needs these for correct client IP and scheme
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# socket.io uses both polling (HTTP) and WebSocket transports
# both are handled by the proxy_pass above

Plusieurs chemins WebSocket

Différents services WebSocket peuvent être routés par chemin vers différents backends. Chaque location exige les mêmes en-têtes d'upgrade. Le bloc map se définit une fois au niveau http et se partage. Réglez read_timeout par service — un chat peut être actif souvent ; des notifications peuvent chômer des heures.

nginx
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;

    # chat application
    location /ws/chat/ {
        proxy_pass http://chat_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 3600s;
    }

    # notifications service
    location /ws/notify/ {
        proxy_pass http://notify_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 86400s;
    }
}

WSS (WebSocket sécurisé)

WSS est WebSocket sur TLS. nginx termine le TLS (gère le certificat) et proxyfie un WebSocket en clair vers le backend. Le backend n'a pas besoin de config TLS. C'est la mise en place de production standard — les navigateurs exigent WSS pour les pages HTTPS (règles de contenu mixte).

nginx
server {
    listen 443 ssl;
    server_name ws.example.com;

    ssl_certificate     /etc/ssl/ws.example.com.crt;
    ssl_certificate_key /etc/ssl/ws.example.com.key;

    location / {
        proxy_pass http://backend:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 86400s;
    }
}

# browser connects with wss://ws.example.com
# nginx terminates TLS, proxies plain WebSocket to the backend
14

En-têtes de sécurité

X-Frame-Options

X-Frame-Options empêche l'intégration de votre site dans des iframes, bloquant les attaques de clickjacking. SAMEORIGIN autorise vos propres pages à s'encadrer. Le remplaçant moderne est CSP frame-ancestors, plus flexible. always garantit que l'en-tête part aussi sur les réponses d'erreur.

nginx
# prevent clickjacking (your site embedded in an iframe)
add_header X-Frame-Options "SAMEORIGIN" always;

# options:
# DENY          - no framing at all
# SAMEORIGIN    - only same-site can frame
# ALLOW-FROM    - deprecated, use CSP frame-ancestors instead

# modern equivalent via Content-Security-Policy
add_header Content-Security-Policy "frame-ancestors 'self'" always;

X-Content-Type-Options

nosniff demande aux navigateurs de se fier à l'en-tête Content-Type et de ne pas renifler le contenu. Sans lui, un navigateur pourrait exécuter une image téléversée comme HTML s'il y détecte du HTML. En-tête à faible effort et forte valeur — activez-le toujours.

nginx
# prevent MIME-type sniffing
add_header X-Content-Type-Options "nosniff" always;

# forces the browser to respect the declared Content-Type
# prevents XSS via uploaded files (e.g., an image containing HTML
# being executed as a script)

# related: block Adobe Flash / PDF cross-domain policies
add_header X-Permitted-Cross-Domain-Policies "none" always;

Content-Security-Policy

CSP est la défense la plus puissante contre le XSS — il liste les sources autorisées pour scripts, styles, images, etc. Commencez en Report-Only pour trouver les violations sans rien casser, puis forcez. 'self' signifie même origine ; 'unsafe-inline' autorise les scripts/styles en ligne (nécessaire à beaucoup d'apps).

nginx
# strict CSP — restricts where resources can load from
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' https://fonts.gstatic.com; connect-src 'self' https://api.example.com; frame-ancestors 'none'; base-uri 'none'; form-action 'self'" always;

# report-only mode (logs violations without blocking)
add_header Content-Security-Policy-Report-Only "default-src 'self'; report-uri /csp-report" always;

X-XSS-Protection

X-XSS-Protection activait le filtre anti-XSS réfléchi intégré du navigateur. Les navigateurs modernes ont retiré cette fonctionnalité au profit de CSP. mode=block empêchait l'assainissement (qui pouvait introduire de nouvelles vulnérabilités) et bloquait simplement la page. Inoffensif pour les vieux navigateurs, mais CSP est la vraie défense.

nginx
# legacy XSS auditor (older browsers)
add_header X-XSS-Protection "1; mode=block" always;

# values:
# 0              - disable the filter
# 1              - enable (sanitize)
# 1; mode=block  - enable and block the page entirely

# NOTE: deprecated in modern browsers (Chrome, Edge, Safari removed it)
# CSP is the modern replacement, but this doesn't hurt to include
# for legacy browser support

Referrer-Policy

Referrer-Policy contrôle combien d'informations d'URL fuient via l'en-tête Referer quand les utilisateurs cliquent des liens. strict-origin-when-cross-origin (le défaut des navigateurs) envoie l'URL complète pour les requêtes même origine mais seulement l'origine pour cross-origin, et rien lors d'une rétrogradation vers HTTP.

nginx
# control what the Referer header contains
add_header Referrer-Policy "strict-origin-when-cross-origin" always;

# options:
# no-referrer                  - never send Referer
# no-referrer-when-downgrade   - default; no Referer on HTTPS->HTTP
# same-origin                  - only same-site
# origin                       - send only scheme+host
# strict-origin                - origin, but not on downgrade
# origin-when-cross-origin     - full for same, origin for cross
# strict-origin-when-cross-origin - recommended default
# unsafe-url                   - send full URL (not recommended)

Permissions-Policy

Permissions-Policy permet de désactiver des fonctionnalités du navigateur (caméra, micro, géolocalisation, etc.) même si la page les demande. Une valeur vide () désigne la fonctionnalité entièrement. Cela limite la portée d'un XSS — un script compromis ne peut pas allumer la caméra si la politique l'interdit.

nginx
# control which browser features the page can use
# (formerly Feature-Policy)
add_header Permissions-Policy "geolocation=(), microphone=(), camera=(), payment=(), usb=(), magnetometer=(), gyroscope=()" always;

# allow only for same origin
add_header Permissions-Policy "geolocation=(self), microphone=(self)" always;

# allow for specific origins
add_header Permissions-Policy "camera=(self https://trusted.com)" always;
15

Contrôle d'accès

Allow/Deny par IP

Les règles allow/deny s'évaluent dans l'ordre ; le premier match gagne. Le deny all final bloque tout ce qui n'est pas explicitement autorisé. Utile pour verrouiller des panneaux d'admin aux IP d'entreprise. Les règles acceptent des plages CIDR ou des IP uniques, en IPv4 comme IPv6.

nginx
location /admin {
    allow 192.168.1.0/24;     # internal network
    allow 10.0.0.0/8;         # VPN range
    allow 203.0.113.5;        # specific IP
    deny all;

    proxy_pass http://backend;
}

# rules are checked in order — first match wins
# if no rule matches, access is allowed by default

Deny all

deny all bloque tout le monde ; associez-le à allow pour une whitelist. L'inverse — deny d'IP précises, allow all — est une blacklist. Les whitelists sont plus sûres (deny par défaut). Sans allow/deny explicite, l'accès est autorisé, donc terminez toujours par deny all pour les zones restreintes.

nginx
# deny all access to a location
location /private {
    deny all;
    return 403;
}

# deny specific IPs, allow everyone else
location / {
    deny 192.168.1.100;        # block one IP
    deny 203.0.113.0/24;       # block a range
    allow all;
}

# deny a range, allow the rest
location /api {
    deny 10.0.0.0/8;
    allow all;
    proxy_pass http://backend;
}

Autoriser un sous-réseau

Les plages d'IP privées (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) ne sont pas routables sur Internet, donc les autoriser restreint l'accès aux réseaux internes. Pour IPv6, ::1 est localhost. Combinez à un VPN pour un accès distant sûr aux outils internes.

nginx
# allow only local/private networks
location /internal {
    allow 192.168.0.0/16;     # private class B
    allow 172.16.0.0/12;      # private class B range
    allow 10.0.0.0/8;         # private class A
    deny all;

    root /var/www/internal;
}

# IPv6
location / {
    allow 2001:db8::/32;      # example IPv6 range
    allow ::1;                # IPv6 localhost
    deny all;
}

Module Geo

geo est optimisé pour les lookups d'IP via un radix tree — bien plus rapide qu'une longue liste allow/deny. Il règle une variable (ici $allowed_ip) selon l'IP client. La forme 'ranges' supporte les plages début-fin d'IP. Utilisez la variable dans if() ou map pour un contrôle d'accès flexible.

nginx
# map IPs to values (binary search, very fast)
geo $allowed_ip {
    default        0;
    192.168.0.0/24 1;
    10.0.0.0/8     1;
    203.0.113.5    1;
}

server {
    location /admin {
        if ($allowed_ip = 0) {
            return 403;
        }
        proxy_pass http://backend;
    }
}

# geo with IP ranges (uses 'ranges' directive)
geo $country_code {
    ranges;
    default                 ZZ;
    10.0.0.0-10.255.255.255 US;
}

Limite par IP (limit_req)

limit_req_zone définit un débit par IP avec $binary_remote_addr (compact). limit_req l'applique. burst tolère de courts pics (file jusqu'à 20). nodelay sert le burst immédiatement plutôt que de l'étaler — bien pour les API. Sans nodelay, les requêtes excédentaires sont retardées, pas rejetées.

nginx
http {
    # define rate limit zone (10 requests/sec per IP)
    limit_req_zone $binary_remote_addr zone=mylimit:10m rate=10r/s;

    server {
        location /api/ {
            limit_req zone=mylimit burst=20 nodelay;
            proxy_pass http://backend;
        }
    }
}

# $binary_remote_addr uses binary form (more memory-efficient)
# 10m zone stores ~160,000 unique IP addresses
# rate=10r/s: 10 requests per second per IP
# burst=20: allow 20 requests to queue
# nodelay: serve the burst immediately (no artificial delay)

Blocage par pays (GeoIP)

Le module GeoIP mappe les IP client vers des codes pays avec une base MaxMind. Combiné à map, on peut bloquer ou autoriser des pays entiers. Note : le GeoLite2 gratuit de MaxMind exige le module tiers maxminddb (l'ancien module GeoIP utilise le vieux format .dat). La précision n'est pas de 100 % — réservez-le au filtrage grossier.

nginx
# requires the GeoIP module and a MaxMind database
geoip_country /usr/share/GeoIP/GeoIP.dat;

map $geoip_country_code $allowed_country {
    default yes;
    CN no;
    RU no;
    KP no;
}

server {
    location / {
        if ($allowed_country = no) {
            return 403;
        }
        proxy_pass http://backend;
    }
}

# GeoIP2 (maxminddb module) for the newer GeoLite2 format
# maxminddb /etc/nginx/geoip2/GeoLite2-Country.mmdb;
# $geoip2_country_code source=$remote_addr country iso_code;
16

Authentification

Mise en place Basic Auth

auth_basic déclenche la boîte de dialogue native utilisateur/mot de passe du navigateur. La chaîne de realm (« Admin Area ») s'affiche à l'utilisateur. auth_basic_user_file pointe vers un fichier htpasswd. Utilisez auth_basic off pour désactiver l'auth dans une sous-location qui doit rester publique.

nginx
location /admin {
    auth_basic "Admin Area";
    auth_basic_user_file /etc/nginx/.htpasswd;

    proxy_pass http://backend;
}

location /public {
    # disable auth inherited from parent location
    auth_basic off;
}

# create users with htpasswd (apache2-utils / httpd-tools):
# htpasswd -c /etc/nginx/.htpasswd user1   (create file)
# htpasswd /etc/nginx/.htpasswd user2      (append, no -c)

Fichier htpasswd

Le fichier htpasswd stocke des paires utilisateur:hash. bcrypt (-B) est le hash le plus fort ; MD5 (-m, défaut) acceptable ; SHA1 (-s) faible ; PLAIN non sécurisé. Restreignez les permissions du fichier pour que seul nginx puisse le lire — il contient des hashs de mots de passe qui ne doivent pas fuir.

nginx
# /etc/nginx/.htpasswd format:
# user1:$apr1$qHR...$hashedpassword
# user2:{PLAIN}plaintext       (insecure!)
# user3:{SHA}base64sha1hash

# generate with htpasswd:
# -c  create new file (overwrites!)
# -B  bcrypt (most secure, recommended)
# -m  MD5 (default, APR1)
# -s  SHA1

# bcrypt (recommended)
# htpasswd -B /etc/nginx/.htpasswd user1

# protect the file permissions
chown root:nginx /etc/nginx/.htpasswd
chmod 640 /etc/nginx/.htpasswd

Auth pour une location précise

auth_basic se hérite dans les locations imbriquées. Pour rendre public un sous-chemin, réglez auth_basic off. Utile quand la plupart de /admin exige l'auth mais /admin/health (endpoint de health check) doit être accessible sans credentials pour les outils de monitoring.

nginx
server {
    # no auth at server level

    location /admin {
        auth_basic "Admin";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }

    location /admin/api {
        # inherits auth from /admin
        proxy_pass http://admin_api;
    }

    location /admin/public {
        # explicitly disable inherited auth
        auth_basic off;
        proxy_pass http://public_api;
    }
}

Allow/Deny avec auth

satisfy any signifie que passer l'un OU l'autre — vérification d'IP ou authentification — donne l'accès ; pratique pour les utilisateurs internes (sans mot de passe) tout en exigeant un mot de passe aux externes. satisfy all exige les deux — l'option la plus restrictive, pour les zones très sensibles.

nginx
# satisfy: ALL (default) or ANY
location / {
    # allow corporate IPs without password
    # require password from outside the corporate network
    satisfy any;

    allow 192.168.0.0/16;
    deny all;

    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;

    proxy_pass http://backend;
}

# satisfy all: must pass BOTH IP check AND auth
# satisfy any: pass EITHER IP check OR auth

Module auth_request

auth_request envoie une sous-requête interne à un service d'auth avant la requête principale. Le service valide le token (JWT, cookie de session, etc.) et retourne 2xx (autoriser) ou 401/403 (refuser). internal empêche l'accès externe à /auth. Cela découple l'auth de votre app.

nginx
# delegate authentication to a subrequest (OAuth, JWT, etc.)
location / {
    auth_request /auth;
    proxy_pass http://backend;
}

location = /auth {
    internal;                    # can't be called directly
    proxy_pass http://auth-service/validate;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

# auth-service returns:
# 2xx -> allow (continue to backend)
# 401/403 -> deny (return to client)
# other -> error

Auth JWT

La validation JWT peut se faire en interne avec njs (module JavaScript de nginx) pour une latence minimale, ou être déléguée à un service externe via auth_request. njs exécute un sous-ensemble de JavaScript dans nginx — rapide mais limité. L'approche auth_request est plus flexible et agnostique du langage.

nginx
# requires the njs (nginx JavaScript) module
js_import auth.js;

location /api/ {
    js_content auth.validateJwt;
    proxy_pass http://backend;
}

# auth.js defines the validateJwt function:
# function validateJwt(r) {
#     var token = r.headersIn.Authorization;
#     if (!token || !verifyJwt(token)) {
#         r.return(401);
#         return;
#     }
# }

# alternative: use auth_request with an external JWT validator service
# more portable than njs, but adds a network hop per request
17

Logging

Access log

access_log enregistre chaque requête. log_format définit quels champs capturer. Le format 'combined' par défaut est compatible Apache. Pour les sites très fréquentés, buffer+flush réduit l'I/O disque en batchant les écritures. syslog expédie les logs à un serveur central pour l'agrégation.

nginx
http {
    log_format main '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent"';

    access_log /var/log/nginx/access.log main;
    # or use the built-in 'combined' format
    access_log /var/log/nginx/access.log combined;
}

# disable access log
access_log off;

# log to syslog
access_log syslog:server=localhost,facility=local7 main;

# buffer writes (reduce I/O)
access_log /var/log/nginx/access.log main buffer=32k flush=5s;

Error log

error_log capture les erreurs nginx et les problèmes upstream. Le niveau filtre la gravité — warn est un bon défaut. debug est très verbeux (réservé au dépannage) et exige une build debug. memory: bufférise les logs en RAM — utile pour diagnostiquer des problèmes de démarrage que le log disque ne capture pas.

nginx
# error log location and severity level
error_log /var/log/nginx/error.log warn;

# levels (low to high severity):
# debug, info, notice, warn, error, crit, alert, emerg

# debug requires nginx built with --with-debug
error_log /var/log/nginx/error.log debug;

# log to memory (for debugging, lost on restart)
error_log memory:32m debug;

# disable (NOT recommended — hides real errors)
error_log /dev/null crit;

Formats de log

Les formats de log personnalisés capturent ce qui vous importe. request_time est le temps total de traitement ; upstream_response_time isole le backend. escape=json produit du JSON valide pour les agrégateurs de logs (ELK, Loki, Datadog). Sans escape=json, des caractères spéciaux d'URI peuvent casser le parsing JSON.

nginx
http {
    # combined (Apache-compatible, the default)
    log_format combined '$remote_addr - $remote_user [$time_local] '
                        '"$request" $status $body_bytes_sent '
                        '"$http_referer" "$http_user_agent"';

    # main with upstream timing
    log_format main '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent" '
                    'rt=$request_time uct="$upstream_connect_time" '
                    'urt="$upstream_response_time"';

    # JSON format for log aggregation (ELK, Loki, etc.)
    log_format json escape=json
        '{"time":"$time_iso8601",'
        '"remote":"$remote_addr",'
        '"method":"$request_method",'
        '"uri":"$request_uri",'
        '"status":$status,'
        '"bytes":$body_bytes_sent,'
        '"ua":"$http_user_agent"}';
}

Logging conditionnel

Le paramètre if= logue conditionnellement selon une variable. map $status permet de ne logger que les erreurs (4xx/5xx), réduisant bruit et usage disque sur les sites très fréquentés. La variable doit être 0/vide pour sauter le log, non nulle pour logger.

nginx
http {
    # don't log successful 2xx/3xx, only errors
    map $status $loggable {
        ~^[23]  0;
        default 1;
    }

    server {
        access_log /var/log/nginx/access.log main if=$loggable;
    }
}

# skip logging for static assets
map $request_uri $log_skip {
    default                    1;
    ~*\.(jpg|png|gif|css|js)$  0;
}
access_log /var/log/nginx/access.log main if=$log_skip;

Rotation des logs

logrotate renomme et compresse les vieux logs. postrotate envoie USR1 à nginx, qui rouvre ses fichiers de log — sans cela, nginx continue d'écrire dans le fichier renommé. sharedscripts exécute postrotate une fois (pas par fichier). delaycompress compresse à la seconde rotation, laissant le log le plus récent non compressé.

nginx
# logrotate config: /etc/logrotate.d/nginx
/var/log/nginx/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 www-data adm
    sharedscripts
    postrotate
        if [ -f /var/run/nginx.pid ]; then
            kill -USR1 $(cat /var/run/nginx.pid)
        fi
    endscript
}

# USR1 signal tells nginx to reopen log files
# without dropping connections
# nginx -s reopen does the same thing

Désactiver le logging

Désactiver access_log pour les health checks et assets statiques réduit sensiblement le bruit de log et l'I/O disque. log_not_found off supprime les entrées 404 du log (utile pour favicon.ico). Gardez toujours error_log actif au moins au niveau 'error' — les échecs silencieux sont durs à diagnostiquer.

nginx
# disable access log entirely
access_log off;

# disable for a specific location
location /health {
    access_log off;
    return 200 "ok\n";
}

# disable for static assets
location ~* \.(jpg|png|gif|ico|css|js)$ {
    access_log off;
    log_not_found off;
}

# only log errors (reduce error log verbosity)
error_log /var/log/nginx/error.log error;
18

Limitation de débit

limit_req_zone

limit_req_zone définit une limite de débit indexée par une variable (souvent l'IP client). La taille de zone (10m) détermine combien de clés uniques peuvent être suivies. rate est la fréquence de requêtes autorisée. Définissez les zones dans le contexte http, appliquez-les dans les locations avec limit_req.

nginx
http {
    # 10 requests per second per IP
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

    # 1 request per second per IP (for login)
    limit_req_zone $binary_remote_addr zone=login:10m rate=1r/s;

    # 100 requests per minute per IP
    limit_req_zone $binary_remote_addr zone=general:10m rate=100r/m;
}

# $binary_remote_addr uses binary form (more memory-efficient than text)
# 10m zone stores ~160,000 unique IP addresses
# rate can be per second (r/s) or per minute (r/m)

limit_req

limit_req applique une zone à une location. burst tolère de courts pics (file jusqu'à N requêtes excédentaires). nodelay sert le burst à pleine vitesse plutôt que de l'étaler — bien pour les API où la latence compte. Sans burst, chaque requête dépassant le débit est rejetée immédiatement.

nginx
http {
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

    server {
        location /api/ {
            limit_req zone=api burst=20 nodelay;
            proxy_pass http://backend;
        }

        location /login {
            limit_req zone=api burst=5 nodelay;
            proxy_pass http://backend;
        }
    }
}

# burst: max number of requests allowed to queue
# nodelay: serve the burst immediately (no artificial throttling)
# without burst: requests exceeding the rate get 503 immediately

limit_conn

limit_conn limite les connexions concurrentes, pas le débit de requêtes. Utile pour empêcher une seule IP d'ouvrir des centains de téléchargements simultanés. Combiné à limit_req (débit), il offre à la fois protection contre les pics et contre la concurrence. limit_conn_zone suit le même motif de zone par clé.

nginx
http {
    # limit concurrent connections per IP
    limit_conn_zone $binary_remote_addr zone=conn_per_ip:10m;

    # limit total connections per server name
    limit_conn_zone $server_name zone=conn_per_server:10m;

    server {
        limit_conn conn_per_ip 10;
        limit_conn conn_per_server 1000;

        location /download {
            limit_conn conn_per_ip 1;  # one download at a time per IP
            proxy_pass http://backend;
        }
    }
}

File de burst

burst est la taille de file des requêtes excédentaires. nodelay sert tout le burst immédiatement (bien pour les API). delay=N en sert N immédiatement et étale le reste au débit configuré (plus lisse). Sans nodelay, toutes les requêtes excédentaires sont retardées pour matcher le débit, répartissant la charge uniformément.

nginx
http {
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

    server {
        location /api/ {
            # burst=20: allow 20 requests to queue
            # nodelay: serve them immediately (no artificial delay)
            limit_req zone=api burst=20 nodelay;

            # delay: first 10 immediate, next 10 delayed, rest rejected
            limit_req zone=api burst=20 delay=10;

            proxy_pass http://backend;
        }
    }
}

# without burst: requests over rate get 503 immediately
# with burst: excess requests queue (default delayed)
# nodelay: queue served at full speed (allows spikes)
# delay=N: first N immediate, rest throttled to the rate

Limitation par IP

Définissez des zones séparées par type d'endpoint avec des débits adaptés. Les endpoints API tolèrent des débits plus élevés ; les endpoints d'auth (login, reset de mot de passe) exigent des limites strictes contre le brute force ; les uploads exigent de très bas débits contre l'abus. burst donne une petite tolérance aux pics légitimes.

nginx
http {
    # different limits for different endpoints
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
    limit_req_zone $binary_remote_addr zone=auth:10m rate=1r/s;
    limit_req_zone $binary_remote_addr zone=upload:10m rate=2r/m;

    server {
        location /api/ {
            limit_req zone=api burst=20 nodelay;
        }

        location /login {
            limit_req zone=auth burst=5 nodelay;
        }

        location /upload {
            limit_req zone=upload burst=3 nodelay;
            client_max_body_size 100M;
        }
    }
}

Réponse personnalisée de rate limit

Par défaut, les requêtes limitées reçoivent 503 (Service Unavailable). 429 (Too Many Requests) est plus sémantiquement correct et attendu par la plupart des API. Utilisez error_page pour retourner un corps JSON expliquant la limite. Incluez un en-tête Retry-After pour que les clients sachent quand relâcher.

nginx
http {
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
    limit_req_status 429;  # default is 503

    server {
        location /api/ {
            limit_req zone=api burst=20 nodelay;

            # custom error response
            error_page 429 = @rate_limited;
        }

        location @rate_limited {
            default_type application/json;
            return 429 '{"error":"rate_limit_exceeded","retry_after":60}';
        }
    }
}

# also available: limit_conn_status 429;
19

Réglages de performance

worker_processes

worker_processes doit matcher le nombre de cœurs CPU — auto le fait automatiquement. Chaque worker est un processus mono-thread qui gère beaucoup de connexions via une boucle d'événements. worker_cpu_affinity épingle les workers sur des cœurs précis, améliorant la localité de cache. L'affinité auto laisse le scheduler de l'OS décider.

nginx
# main context
worker_processes auto;  # one per CPU core (recommended)

# or set an explicit count
worker_processes 4;

# each worker handles connections independently
# 'auto' uses the number of available CPU cores

# CPU affinity (pin workers to specific cores)
worker_processes auto;
worker_cpu_affinity auto;

# or manual bitmask (one mask per worker)
worker_processes 4;
worker_cpu_affinity 0001 0010 0100 1000;

worker_connections

worker_connections est par worker ; la capacité totale est worker_processes * worker_connections. Elle est aussi bornée par la limite de descripteurs de fichiers de l'OS (worker_rlimit_nofile). Il faut augmenter à la fois la limite nginx et celle de l'OS (limits.conf ou LimitNOFILE de systemd). multi_accept saisit toutes les connexions en attente d'un coup.

nginx
events {
    # connections per worker process
    worker_connections 4096;

    # accept multiple connections at once under high load
    multi_accept on;
}

# total max connections = worker_processes * worker_connections
# but also bounded by worker_rlimit_nofile (file descriptor limit)

# main context — raise the FD limit
worker_rlimit_nofile 65535;

# also raise system limits (outside nginx):
# /etc/security/limits.conf:
#   * soft nofile 65535
#   * hard nofile 65535

keepalive_timeout

Le keepalive client réutilise les connexions pour plusieurs requêtes, réduisant la latence. keepalive_timeout est la durée pendant laquelle une connexion inactive reste ouverte. Le keepalive upstream (directive keepalive dans upstream) met en cache les connexions vers les backends — réglez Connection à vide pour que nginx n'envoie pas 'close'.

nginx
http {
    # keep-alive timeout (client side)
    keepalive_timeout 65s;
    keepalive_requests 1000;  # max requests per connection

    # upstream keepalive (reuse connections to backends)
    upstream backend {
        server 10.0.0.1:8080;
        keepalive 32;  # cache of 32 idle upstream connections
    }

    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";  # clear to enable keepalive
    }
}

sendfile et tcp_nopush

sendfile utilise un chemin zero-copy au niveau noyau pour envoyer des fichiers, contournant les buffers user-space — bien plus rapide pour les fichiers statiques. tcp_nopush accompagne sendfile pour envoyer en-têtes et début de fichier en un paquet. tcp_nodelay désactive Nagle pour une latence minimale. aio threads décharge l'I/O disque de la boucle d'événements.

nginx
http {
    # use kernel sendfile() for static files (zero-copy)
    sendfile on;

    # send headers + start of file in one TCP packet
    tcp_nopush on;

    # disable Nagle's algorithm (send small packets immediately)
    tcp_nodelay on;

    # for static file serving
    location /static/ {
        sendfile on;
        tcp_nopush on;
        aio threads;  # asynchronous I/O via thread pool
        root /var/www;
    }
}

# sendfile: zero-copy file transfer (kernel space, no user-space copy)
# tcp_nopush: coalesce headers + file data into one packet
# tcp_nodelay: don't wait to batch small packets (low latency)

Tailles de buffers

Réglez les buffers selon votre trafic. client_max_body_size plafonne la taille des uploads (défaut 1M — trop petit pour des fichiers). Les buffers proxy/fastcgi accueillent les réponses upstream ; trop petits, ils débordent sur disque. large_client_header_buffers gère les URLs/cookies longs. Surveillez les erreurs de « buffer overflow ».

nginx
http {
    # client body buffer (in-memory before writing to disk)
    client_body_buffer_size 16k;
    client_max_body_size 50m;

    # client header buffers
    client_header_buffer_size 1k;
    large_client_header_buffers 4 8k;

    # proxy buffers (responses from upstream)
    proxy_buffer_size 4k;
    proxy_buffers 8 4k;
    proxy_busy_buffers_size 16k;

    # fastcgi buffers (responses from PHP-FPM, etc.)
    fastcgi_buffer_size 4k;
    fastcgi_buffers 8 4k;
}

# if a request body exceeds client_body_buffer_size,
# nginx writes it to a temp file (slower)

Open file cache

open_file_cache met en cache les descripteurs de fichiers et métadonnées, évitant les syscalls open()/stat() répétés pour les fichiers populaires. Cela accélère nettement le service de fichiers statiques. valid contrôle la fréquence de revérification du fichier (attrape les mises à jour). min_uses évite de cacher des requêtes ponctuelles. Cachez aussi les erreurs pour éviter des ouvertures échouées répétées.

nginx
http {
    open_file_cache max=10000 inactive=20s;
    open_file_cache_valid 30s;
    open_file_cache_min_uses 2;
    open_file_cache_errors on;

    server {
        root /var/www/html;

        location / {
            open_file_cache max=10000 inactive=20s;
            open_file_cache_valid 30s;
            try_files $uri $uri/ =404;
        }
    }
}

# caches file descriptors, sizes, modification times
# reduces stat() and open() syscalls for popular files
# max=10000: cache up to 10000 files
# inactive=20s: remove if not accessed in 20 seconds
# min_uses=2: only cache files accessed 2+ times
# valid=30s: re-validate cache every 30s
20

Déploiement Docker

Nginx dans Docker

L'image officielle nginx sert /usr/share/nginx/html par défaut et lit la config dans /etc/nginx. Montez votre config et contenu en volumes. :ro (lecture seule) empêche le conteneur de modifier les fichiers de l'hôte. nginx -s reload prend en compte les changements de config sans recréer le conteneur.

nginx
# run the official nginx image
docker run -d --name nginx \
    -p 80:80 -p 443:443 \
    -v /etc/nginx/nginx.conf:/etc/nginx/nginx.conf:ro \
    -v /var/www/html:/usr/share/nginx/html:ro \
    -v /etc/nginx/conf.d:/etc/nginx/conf.d:ro \
    nginx:latest

# interactive shell into the running container
docker exec -it nginx sh

# reload config without restarting the container
docker exec nginx nginx -s reload

# view logs
docker logs nginx
docker logs -f nginx

Docker Compose

Docker Compose orchestre nginx avec ses backends. expose rend un port accessible aux services liés (pas à l'hôte). depends_on garantit que le backend démarre d'abord. restart: unless-stopped survit aux redémarrages mais respecte les arrêts manuels. Montez les logs avec accès en écriture (sans :ro) pour que nginx puisse y écrire.

nginx
version: '3.8'
services:
  nginx:
    image: nginx:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./conf.d:/etc/nginx/conf.d:ro
      - ./html:/usr/share/nginx/html:ro
      - ./certs:/etc/nginx/certs:ro
      - ./logs:/var/log/nginx
    depends_on:
      - backend
    restart: unless-stopped

  backend:
    image: myapp:latest
    expose:
      - "3000"

Image nginx personnalisée

Cuire la config dans l'image rend les déploiements immuables et reproductibles — pas de montages de volumes à l'exécution. La variante alpine garde l'image minuscule (~7 Mo de base). Idéal pour Kubernetes ou CI/CD où l'on veut un artefact autonome. Reconstruisez pour mettre à jour la config.

nginx
# Dockerfile
FROM nginx:alpine

# copy custom config
COPY nginx.conf /etc/nginx/nginx.conf
COPY conf.d/ /etc/nginx/conf.d/

# copy static files
COPY html/ /usr/share/nginx/html/

# copy SSL certificates
COPY certs/ /etc/nginx/certs/

# build and run
# docker build -t mynginx .
# docker run -d -p 80:80 mynginx

# alpine is ~7MB; the image stays small
# bake config in for immutable deployments

Montages de volumes

Les montages de volumes permettent d'itérer sur la config sans reconstruire l'image — idéal en développement. Monter un répertoire est robuste ; monter un fichier unique peut casser si le fichier hôte n'existe pas (Docker crée un répertoire à la place). Les volumes nommés persistent entre recréations de conteneurs et sont gérés par Docker.

nginx
# mount config and content as volumes (dev workflow)
docker run -d --name nginx \
    -p 80:80 \
    -v $(pwd)/nginx.conf:/etc/nginx/nginx.conf:ro \
    -v $(pwd)/conf.d:/etc/nginx/conf.d:ro \
    -v $(pwd)/html:/usr/share/nginx/html:ro \
    -v $(pwd)/logs:/var/log/nginx \
    nginx:alpine

# read-only mounts (:ro) for security
# logs need write access (no :ro)
# use named volumes for persistent data:
#   -v nginx_logs:/var/log/nginx

# IMPORTANT: mounting a single file (nginx.conf) requires
# the file to exist on the host, or Docker creates a directory

Reverse proxy dans Docker

Dans Docker Compose, les services se résolvent par nom de service (app1, app2). L'upstream de nginx peut référencer ces noms directement — pas besoin d'adresses IP. Cela fait de nginx un puissant équilibreur pour les apps conteneurisées. Utilisez le réseau Compose par défaut, ou définissez-en un personnalisé pour l'isolation.

nginx
# nginx as reverse proxy for other containers
version: '3.8'
services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - app1
      - app2
    restart: unless-stopped

  app1:
    image: myapp:latest

  app2:
    image: myapp:latest

# nginx.conf:
# upstream apps {
#     server app1:3000;
#     server app2:3000;
# }
# server {
#     listen 80;
#     location / { proxy_pass http://apps; }
# }

Health check

Les health checks permettent à Docker (et aux orchestrateurs comme Swarm) de savoir si nginx sert réellement, pas seulement s'il tourne. wget --spider vérifie le statut HTTP sans télécharger le corps. start_period retarde la première vérification pour laisser nginx démarrer. Dans Kubernetes, utilisez plutôt une sonde readiness/liveness que le HEALTHCHECK Docker.

nginx
# Dockerfile with a health check
FROM nginx:alpine

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD wget --quiet --tries=1 --spider http://localhost/ || exit 1

COPY nginx.conf /etc/nginx/nginx.conf

# docker-compose health check
version: '3.8'
services:
  nginx:
    image: nginx:alpine
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 5s

# start_period gives nginx time to boot before checking
# a failed health check marks the container unhealthy

Was this helpful?