dynamic-etag: módulo de NGINX para añadir ETag al contenido dinámico
Instalación
Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, entre otras:
- RedHat Enterprise Linux 7, 8, 9 y 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 y 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
Habilita el módulo añadiendo lo siguiente al principio de /etc/nginx/nginx.conf:
load_module modules/ngx_http_dynamic_etag_module.so;
Este documento describe nginx-module-dynamic-etag v0.3.0 publicado el 14 de noviembre de 2026.
ETag para las respuestas que tu aplicación genera al vuelo.
NGINX añade un ETag a los archivos estáticos, y nada a lo que proviene de PHP-FPM,
una aplicación proxificada o cualquier otro upstream. Esas páginas se descargan
por completo en cada visita, incluso cuando no ha cambiado ni un byte. Este módulo calcula el hash del cuerpo de la respuesta, envía el hash como ETag y responde a un If-None-Match coincidente con 304 Not Modified y sin cuerpo.
Funciona con todos los módulos upstream: proxy_pass, fastcgi_pass,
uwsgi_pass, scgi_pass, grpc_pass.
Sinopsis
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
Cómo funciona
El ETag tiene que estar en la cabecera de la respuesta, y la cabecera se envía antes que el
cuerpo. Por eso el módulo retiene la respuesta: recopila el cuerpo a medida que el
upstream lo entrega, calcula el hash de todo él (MD5) y solo entonces envía la cabecera,
ya con el ETag, seguida del cuerpo.
- El hash siempre cubre el cuerpo completo, sin importar cómo llegue: de una pieza
o en muchas, con
proxy_bufferingactivado o desactivado, desde memoria o desde un archivo temporal al que NGINX lo haya volcado. - Un cuerpo mayor que
dynamic_etag_buffer_sizeno recibeETagy se transmite sin modificar. Nunca hay un hash parcial. - Las peticiones condicionales las responde NGINX mismo, contra el
ETagcalculado:If-None-Matchrecibe un304, unIf-Matchfallido recibe un412. - El hash del cuerpo se calcula antes de la compresión.
gzipy otros filtros de compresión debilitan entonces elETag(W/"..."), como hacen con los archivos estáticos.
Directivas
dynamic_etag
- sintaxis:
dynamic_etag on | off | $variable - valor predeterminado:
off - contexto:
http,server,location
Habilita el ETag para las respuestas de upstream. Con una variable, el ETag se añade
cuando su valor es on; consulta Uso condicional.
dynamic_etag_types
- sintaxis:
dynamic_etag_types mime-type ... - valor predeterminado:
text/html - contexto:
http,server,location
Añade el ETag a las respuestas con los tipos MIME listados, además de
text/html. El valor especial * coincide con cualquier tipo.
dynamic_etag_strength
- sintaxis:
dynamic_etag_strength strong | weak | $variable - valor predeterminado:
strong - contexto:
http,server,location
Hace que el ETag generado sea fuerte ("...") o débil (W/"..."). Un ETag débil
indica que la página es equivalente, no idéntica byte a byte. Con una variable, el
ETag es débil cuando su valor es weak.
dynamic_etag_buffer_size
- sintaxis:
dynamic_etag_buffer_size size - valor predeterminado:
1m - contexto:
http,server,location
El cuerpo de respuesta más grande que el módulo mantiene en memoria para calcular el hash. Una respuesta mayor
se envía sin ETag, exactamente como NGINX la enviaría con el módulo desactivado.
Qué respuestas reciben un ETag
Todas estas condiciones tienen que cumplirse:
- la respuesta proviene de un upstream (no de un archivo estático,
returno una página de error: NGINX gestiona los archivos estáticos por sí mismo); - su estado es
200; - su tipo está listado en
dynamic_etag_types; - la petición no es
HEAD(no hay cuerpo que hashear); - el cuerpo no está vacío y cabe en
dynamic_etag_buffer_size; - el upstream no envió un
ETagpropio. Ese se conserva, y NGINX responde a las peticiones condicionales contra él.
Notas
La página tiene que ser la misma para obtener el mismo ETag. Una página que incluye una
marca de tiempo, un token aleatorio o un nonce por petición cambia en cada petición, y
también lo hace su hash. Compruébalo con:
diff <(curl -s https://example.com/) <(curl -s https://example.com/) && echo stable
La respuesta se envía cuando está completa. El cliente recibe el primer
byte una vez que la aplicación ha producido el último. Para una página normal eso
supone unos pocos milisegundos de diferencia; para una respuesta que se transmite en streaming a propósito
(salida de progreso, server-sent events) deja dynamic_etag desactivado.
Una respuesta que el upstream no logra terminar no se envía en absoluto. Si la
aplicación muere a mitad de página, el cliente recibe una conexión cerrada, no media página
con un 200 y un ETag.
Probar con curl. curl -I envía una petición HEAD, que no recibe
ETag. Usa curl -sI -X GET en su lugar.
Uso condicional
Las directivas no son válidas dentro de if. Usa 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;
}
}