Saltar a contenido

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_buffering activado o desactivado, desde memoria o desde un archivo temporal al que NGINX lo haya volcado.
  • Un cuerpo mayor que dynamic_etag_buffer_size no recibe ETag y se transmite sin modificar. Nunca hay un hash parcial.
  • Las peticiones condicionales las responde NGINX mismo, contra el ETag calculado: If-None-Match recibe un 304, un If-Match fallido recibe un 412.
  • El hash del cuerpo se calcula antes de la compresión. gzip y otros filtros de compresión debilitan entonces el ETag (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, return o 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 ETag propio. 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;
    }
}