dynamic-etag : module NGINX pour ajouter un ETag au contenu dynamique
Installation
Vous pouvez installer ce module sur toute distribution basée sur RHEL, notamment, mais sans s'y limiter :
- RedHat Enterprise Linux 7, 8, 9 et 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 et Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-dynamic-etag
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-dynamic-etag
Activez le module en ajoutant ce qui suit au début de /etc/nginx/nginx.conf :
load_module modules/ngx_http_dynamic_etag_module.so;
Ce document décrit nginx-module-dynamic-etag v0.3.0 publié le 14 novembre 2026.
Un ETag pour les réponses que votre application génère à la volée.
NGINX ajoute un ETag aux fichiers statiques, et rien à ce qui provient de PHP-FPM,
d'une application proxifiée ou de tout autre upstream. Ces pages sont alors téléchargées
intégralement à chaque visite, même lorsqu'aucun octet n'a changé. Ce module calcule le hash du
corps de la réponse, l'envoie comme ETag, et répond à un If-None-Match correspondant
par 304 Not Modified sans corps.
Il fonctionne avec tous les modules upstream : proxy_pass, fastcgi_pass,
uwsgi_pass, scgi_pass, grpc_pass.
Synopsis
location ~ \.php$ {
dynamic_etag on;
fastcgi_pass unix:/run/php-fpm/www.sock;
include fastcgi_params;
}
$ curl -sI -X GET https://example.com/ | grep -i etag
ETag: "6f5902ac237024bdd0c176cb93063dc4"
$ curl -s -o /dev/null -w '%{http_code} %{size_download}\n' \
-H 'If-None-Match: "6f5902ac237024bdd0c176cb93063dc4"' https://example.com/
304 0
Fonctionnement
L'ETag doit figurer dans l'en-tête de la réponse, et l'en-tête est envoyé avant le
corps. Le module retient donc la réponse : il collecte le corps au fur et à mesure que
l'upstream le livre, en calcule le hash (MD5) dans son intégralité, et n'envoie qu'ensuite l'en-tête,
désormais muni de l'ETag, suivi du corps.
- Le hash couvre toujours le corps entier, quelle que soit la façon dont il arrive : en un seul
bloc ou en plusieurs, avec
proxy_bufferingactivé ou désactivé, depuis la mémoire ou depuis un fichier temporaire dans lequel NGINX l'a stocké. - Un corps plus grand que
dynamic_etag_buffer_sizene reçoit pas d'ETaget est transmis tel quel. Il n'y a jamais de hash partiel. - Les requêtes conditionnelles sont traitées par NGINX lui-même, sur la base de l'
ETagcalculé : unIf-None-Matchreçoit un304, unIf-Matchnon satisfait reçoit un412. - Le corps est haché avant compression.
gzipet les autres filtres de compression affaiblissent ensuite l'ETag(W/"..."), comme ils le font pour les fichiers statiques.
Directives
dynamic_etag
- syntaxe :
dynamic_etag on | off | $variable - défaut :
off - contexte :
http,server,location
Active l'ETag pour les réponses upstream. Avec une variable, l'ETag est ajouté
lorsque sa valeur est on ; voir Utilisation conditionnelle.
dynamic_etag_types
- syntaxe :
dynamic_etag_types mime-type ... - défaut :
text/html - contexte :
http,server,location
Ajoute l'ETag aux réponses dont les types MIME figurent dans la liste, en plus de
text/html. La valeur spéciale * correspond à tout type.
dynamic_etag_strength
- syntaxe :
dynamic_etag_strength strong | weak | $variable - défaut :
strong - contexte :
http,server,location
Rend l'ETag généré fort ("...") ou faible (W/"..."). Un ETag faible
signifie que la page est équivalente, et non identique octet pour octet. Avec une variable,
l'ETag est faible lorsque sa valeur est weak.
dynamic_etag_buffer_size
- syntaxe :
dynamic_etag_buffer_size size - défaut :
1m - contexte :
http,server,location
La taille maximale du corps de réponse que le module conserve en mémoire pour le hacher. Une réponse
plus grande est envoyée sans ETag, exactement comme NGINX l'enverrait avec le module désactivé.
Quelles réponses reçoivent un ETag
Toutes les conditions suivantes doivent être remplies :
- la réponse provient d'un upstream (pas d'un fichier statique, d'un
returnou d'une page d'erreur : NGINX gère lui-même les fichiers statiques) ; - son statut est
200; - son type figure dans
dynamic_etag_types; - la requête n'est pas
HEAD(il n'y a pas de corps à hacher) ; - le corps n'est pas vide et tient dans
dynamic_etag_buffer_size; - l'upstream n'a pas envoyé d'
ETagde son propre chef. Celui-ci est conservé, et NGINX traite les requêtes conditionnelles sur sa base.
Remarques
La page doit être identique pour obtenir le même ETag. Une page qui intègre un
horodatage, un jeton aléatoire ou un nonce propre à chaque requête change à chaque requête, et
son hash aussi. Vérifiez avec :
diff <(curl -s https://example.com/) <(curl -s https://example.com/) && echo stable
La réponse est envoyée lorsqu'elle est complète. Le client reçoit le premier
octet une fois que l'application a produit le dernier. Pour une page ordinaire, cela représente
quelques millisecondes de différence ; pour une réponse qui diffuse volontairement en flux
(sortie de progression, server-sent events), laissez dynamic_etag désactivé.
Une réponse que l'upstream ne parvient pas à terminer n'est pas envoyée du tout. Si
l'application s'interrompt en cours de page, le client reçoit une connexion fermée, et non une demi-page
avec un 200 et un ETag.
Tester avec curl. curl -I envoie une requête HEAD, qui ne reçoit pas
d'ETag. Utilisez plutôt curl -sI -X GET.
Utilisation conditionnelle
Les directives ne sont pas valides à l'intérieur de if. Utilisez map :
map $request_uri $dyn_etag {
default on;
~^/checkout off;
~^/api/ off;
}
map $http_user_agent $etag_strength {
default strong;
~*legacybot weak;
}
server {
location / {
dynamic_etag $dyn_etag;
dynamic_etag_strength $etag_strength;
proxy_pass http://backend;
}
}