Aller au contenu

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_buffering activé 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_size ne reçoit pas d'ETag et 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'ETag calculé : un If-None-Match reçoit un 304, un If-Match non satisfait reçoit un 412.
  • Le corps est haché avant compression. gzip et 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 return ou 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'ETag de 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;
    }
}