Zum Inhalt

dynamic-etag: NGINX-Modul zum Hinzufügen von ETag zu dynamischen Inhalten

Installation

Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:

  • RedHat Enterprise Linux 7, 8, 9 und 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 und 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

Aktivieren Sie das Modul, indem Sie Folgendes am Anfang von /etc/nginx/nginx.conf hinzufügen:

load_module modules/ngx_http_dynamic_etag_module.so;

Dieses Dokument beschreibt nginx-module-dynamic-etag v0.3.0 veröffentlicht am 14. November 2026.


ETag für die Antworten, die Ihre Anwendung im laufenden Betrieb erzeugt.

NGINX fügt statischen Dateien ein ETag hinzu und nichts dem, was von PHP-FPM, einer proxied Anwendung oder einem anderen Upstream kommt. Diese Seiten werden dann bei jedem Besuch vollständig heruntergeladen, selbst wenn sich kein Byte geändert hat. Dieses Modul hasht den Antwort-Body, sendet den Hash als ETag und beantwortet ein passendes If-None-Match mit 304 Not Modified und ohne Body.

Es funktioniert mit jedem Upstream-Modul: 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

Funktionsweise

Das ETag muss im Antwort-Header stehen, und der Header wird vor dem Body gesendet. Daher hält das Modul die Antwort zurück: Es sammelt den Body, während der Upstream ihn liefert, hasht ihn vollständig (MD5) und sendet erst dann den Header, nun mit dem ETag, gefolgt vom Body.

  • Der Hash umfasst immer den gesamten Body, egal wie er ankommt: in einem Stück oder in vielen, mit proxy_buffering an oder aus, aus dem Speicher oder aus einer temporären Datei, in die NGINX ihn ausgelagert hat.
  • Ein Body, der größer als dynamic_etag_buffer_size ist, erhält kein ETag und wird unverändert weitergegeben. Es gibt nie einen partiellen Hash.
  • Bedingte Anfragen werden von NGINX selbst gegen das berechnete ETag beantwortet: If-None-Match erhält ein 304, ein fehlgeschlagenes If-Match erhält ein 412.
  • Der Body wird vor der Komprimierung gehasht. gzip und andere Komprimierungsfilter schwächen dann das ETag ab (W/"..."), wie sie es auch bei statischen Dateien tun.

Direktiven

dynamic_etag

  • Syntax: dynamic_etag on | off | $variable
  • Standard: off
  • Kontext: http, server, location

Aktiviert das ETag für Upstream-Antworten. Bei einer Variable wird das ETag hinzugefügt, wenn ihr Wert on ist; siehe Bedingte Verwendung.

dynamic_etag_types

  • Syntax: dynamic_etag_types mime-type ...
  • Standard: text/html
  • Kontext: http, server, location

Fügt das ETag zu Antworten mit den aufgelisteten MIME-Typen zusätzlich zu text/html hinzu. Der spezielle Wert * entspricht jedem Typ.

dynamic_etag_strength

  • Syntax: dynamic_etag_strength strong | weak | $variable
  • Standard: strong
  • Kontext: http, server, location

Macht das generierte ETag stark ("...") oder schwach (W/"..."). Ein schwaches ETag besagt, dass die Seite äquivalent ist, nicht byte-für-byte identisch. Bei einer Variable ist das ETag schwach, wenn ihr Wert weak ist.

dynamic_etag_buffer_size

  • Syntax: dynamic_etag_buffer_size size
  • Standard: 1m
  • Kontext: http, server, location

Der größte Antwort-Body, den das Modul zum Hashen im Speicher hält. Eine größere Antwort wird ohne ETag gesendet, genau so, wie NGINX sie mit deaktiviertem Modul senden würde.

Welche Antworten erhalten ein ETag

All dies muss zutreffen:

  • die Antwort kommt von einem Upstream (nicht von einer statischen Datei, return oder einer Fehlerseite: statische Dateien behandelt NGINX selbst);
  • ihr Status ist 200;
  • ihr Typ ist in dynamic_etag_types aufgelistet;
  • die Anfrage ist kein HEAD (es gibt keinen Body zum Hashen);
  • der Body ist nicht leer und passt in dynamic_etag_buffer_size;
  • der Upstream hat kein eigenes ETag gesendet. Dieses wird beibehalten, und NGINX beantwortet bedingte Anfragen gegen dieses.

Hinweise

Die Seite muss gleich sein, um dasselbe ETag zu erhalten. Eine Seite, die einen Zeitstempel, ein zufälliges Token oder eine pro Anfrage erzeugte Nonce einbettet, ändert sich bei jeder Anfrage, und damit auch ihr Hash. Prüfen Sie mit:

diff <(curl -s https://example.com/) <(curl -s https://example.com/) && echo stable

Die Antwort wird gesendet, wenn sie vollständig ist. Der Client erhält das erste Byte, sobald die Anwendung das letzte erzeugt hat. Bei einer gewöhnlichen Seite ist das eine Verzögerung von wenigen Millisekunden; bei einer Antwort, die absichtlich streamt (Fortschrittsausgabe, Server-Sent Events), lassen Sie dynamic_etag ausgeschaltet.

Eine Antwort, die der Upstream nicht zu Ende bringt, wird überhaupt nicht gesendet. Wenn die Anwendung mitten auf der Seite abstürzt, erhält der Client eine geschlossene Verbindung, nicht eine halbe Seite mit einem 200 und einem ETag.

Testen mit curl. curl -I sendet eine HEAD-Anfrage, die kein ETag erhält. Verwenden Sie stattdessen curl -sI -X GET.

Bedingte Verwendung

Die Direktiven sind innerhalb von if nicht gültig. Verwenden Sie 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;
    }
}