Zum Inhalt

headers-more: NGINX Headers More dynamisches Modul

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-headers-more

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-headers-more

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

load_module modules/ngx_http_headers_more_filter_module.so;

Dieses Dokument beschreibt nginx-module-headers-more v0.33, veröffentlicht am 28. Juni 2022.

 # set the Server output header
 more_set_headers 'Server: my-server';

 # set and clear output headers
 location /bar {
     more_set_headers 'X-MyHeader: blah' 'X-MyHeader2: foo';
     more_set_headers -t 'text/plain text/css' 'Content-Type: text/foo';
     more_set_headers -s '400 404 500 503' -s 413 'Foo: Bar';
     more_clear_headers 'Content-Type';

     # your proxy_pass/memcached_pass/or any other config goes here...
 }

 # set output headers
 location /type {
     more_set_headers 'Content-Type: text/plain';
     # ...
 }

 # set input headers
 location /foo {
     set $my_host 'my dog';
     more_set_input_headers 'Host: $my_host';
     more_set_input_headers -t 'text/plain' 'X-Foo: bah';

     # now $host and $http_host have their new values...
     # ...
 }

 # replace input header X-Foo *only* if it already exists
 more_set_input_headers -r 'X-Foo: howdy';

Beschreibung

Dieses Modul ermöglicht es Ihnen, beliebige Ausgabe- oder Eingabeköpfe hinzuzufügen, festzulegen oder zu löschen, die Sie angeben.

Dies ist eine erweiterte Version des Standard- headers Moduls, da es zusätzliche Funktionen wie das Zurücksetzen oder Löschen von "eingebauten Köpfen" wie Content-Type, Content-Length und Server bietet.

Es ermöglicht Ihnen auch, ein optionales Kriterium für den HTTP-Statuscode mit der -s Option und ein optionales Kriterium für den Inhaltstyp mit der -t Option anzugeben, während Sie die Ausgabeheader mit den more_set_headers und more_clear_headers Direktiven ändern. Zum Beispiel,

 more_set_headers -s 404 -t 'text/html' 'X-Foo: Bar';

Sie können auch mehrere MIME-Typen in einer einzigen -t Option filtern. Zum Beispiel,

more_set_headers -t 'text/html text/plain' 'X-Foo: Bar';

Verwenden Sie niemals andere Parameter wie charset=utf-8 in den Werten der -t Option; sie werden nicht wie erwartet funktionieren.

Eingabeköpfe können ebenfalls geändert werden. Zum Beispiel

 location /foo {
     more_set_input_headers 'Host: foo' 'User-Agent: faked';
     # now $host, $http_host, $user_agent, and
     #   $http_user_agent all have their new values.
 }

Die Option -t ist auch in den more_set_input_headers und more_clear_input_headers Direktiven (für die Filterung von Anfrageheadern) verfügbar, während die -s Option nicht erlaubt ist.

Im Gegensatz zum Standard- headers Modul gelten die Direktiven dieses Moduls standardmäßig für alle Statuscodes, einschließlich 4xx und 5xx.

Direktiven

more_set_headers

syntax: more_set_headers [-t <content-type list>]... [-s <status-code list>]... <new-header>...

default: nein

context: http, server, location, location if

phase: output-header-filter

Ersetzt (falls vorhanden) oder fügt (falls nicht vorhanden) die angegebenen Ausgabeheader hinzu, wenn der Statuscode der Antwort mit den durch die -s Option angegebenen Codes übereinstimmt UND der Inhaltstyp der Antwort mit den durch die -t Option angegebenen Typen übereinstimmt.

Wenn entweder -s oder -t nicht angegeben oder einen leeren Listenwert hat, ist kein Abgleich erforderlich. Daher setzt die folgende Direktive den Server Ausgabeheader auf den benutzerdefinierten Wert für jeden Statuscode und jeden Inhaltstyp:

   more_set_headers    "Server: my_server";

Vorhandene Antwortheader mit demselben Namen werden immer überschrieben. Wenn Sie Header schrittweise hinzufügen möchten, verwenden Sie stattdessen die Standard- add_header Direktive.

Eine einzelne Direktive kann mehrere Ausgabeheader setzen/hinzufügen. Zum Beispiel

   more_set_headers 'Foo: bar' 'Baz: bah';

Mehrere Vorkommen der Optionen sind in einer einzelnen Direktive erlaubt. Ihre Werte werden zusammengeführt. Zum Beispiel

   more_set_headers -s 404 -s '500 503' 'Foo: bar';

ist gleichwertig zu

   more_set_headers -s '404 500 503' 'Foo: bar';

Der neue Header sollte eine der folgenden Formen haben:

  1. Name: Value
  2. Name:
  3. Name

Die letzten beiden löschen effektiv den Wert des Headers Name.

Nginx-Variablen sind in Headerwerten erlaubt. Zum Beispiel:

    set $my_var "dog";
    more_set_headers "Server: $my_var";

Aber Variablen funktionieren nicht in Header-Schlüsseln aus Leistungsgründen.

Mehrere Setzen/Löschen-Header-Direktiven sind in einem einzelnen Standort erlaubt, und sie werden nacheinander ausgeführt.

Direktiven, die von einem übergeordneten Geltungsbereich (z. B. http-Block oder Serverblöcke) geerbt werden, werden vor den Direktiven im Standortblock ausgeführt.

Beachten Sie, dass more_set_headers zwar in location if-Blöcken erlaubt ist, es jedoch nicht in den server if-Blöcken erlaubt ist, wie in

   ?  # Dies ist NICHT erlaubt!
   ?  server {
   ?      if ($args ~ 'download') {
   ?          more_set_headers 'Foo: Bar';
   ?      }
   ?      ...
   ?  }

Hinter den Kulissen wird die Verwendung dieser Direktive und ihrer Freundin more_clear_headers (träge) einen Ausgabeheader-Filter registrieren, der r->headers_out auf die von Ihnen angegebene Weise ändert.

more_clear_headers

syntax: more_clear_headers [-t <content-type list>]... [-s <status-code list>]... <new-header>...

default: nein

context: http, server, location, location if

phase: output-header-filter

Löscht die angegebenen Ausgabeheader.

Tatsächlich,

    more_clear_headers -s 404 -t 'text/plain' Foo Baz;

ist genau gleichwertig zu

    more_set_headers -s 404 -t 'text/plain' "Foo: " "Baz: ";

oder

    more_set_headers -s 404 -t 'text/plain' Foo Baz

Siehe more_set_headers für weitere Details.

Das Wildcard-Zeichen * kann auch am Ende des Header-Namens verwendet werden, um ein Muster anzugeben. Zum Beispiel löscht die folgende Direktive effektiv alle Ausgabeheader, die mit "X-Hidden-" beginnen:

 more_clear_headers 'X-Hidden-*';

Die Unterstützung für das * Wildcard wurde erstmals in v0.09 eingeführt.

more_set_input_headers

syntax: more_set_input_headers [-r] [-t <content-type list>]... <new-header>...

default: nein

context: http, server, location, location if

phase: rewrite tail

Sehr ähnlich wie more_set_headers, mit dem Unterschied, dass es auf Eingabeköpfe (oder Anfrageheader) wirkt und nur die -t Option unterstützt.

Beachten Sie, dass die Verwendung der -t Option in dieser Direktive bedeutet, dass nach dem Content-Type Anfrage Header gefiltert wird, anstatt nach dem Antwortheader.

Hinter den Kulissen wird die Verwendung dieser Direktive und ihrer Freundin more_clear_input_headers (träge) einen rewrite phase Handler registrieren, der r->headers_in auf die von Ihnen angegebene Weise ändert. Beachten Sie, dass sie immer am Ende der rewrite Phase ausgeführt wird, sodass sie nach dem Standard- rewrite module ausgeführt wird und auch in Unteranfragen funktioniert.

Wenn die -r Option angegeben ist, werden die Header nur dann auf die neuen Werte ersetzt, wenn sie bereits existieren.

more_clear_input_headers

syntax: more_clear_input_headers [-t <content-type list>]... <new-header>...

default: nein

context: http, server, location, location if

phase: rewrite tail

Löscht die angegebenen Eingabeköpfe.

Tatsächlich,

    more_clear_input_headers -t 'text/plain' Foo Baz;

ist genau gleichwertig zu

    more_set_input_headers -t 'text/plain' "Foo: " "Baz: ";

oder

    more_set_input_headers -t 'text/plain' Foo Baz

Um die Anfrageheader "Foo" und "Baz" für alle eingehenden Anfragen unabhängig vom Inhaltstyp zu entfernen, können wir schreiben

    more_clear_input_headers "Foo" "Baz";

Siehe more_set_input_headers für weitere Details.

Das Wildcard-Zeichen * kann auch am Ende des Header-Namens verwendet werden, um ein Muster anzugeben. Zum Beispiel löscht die folgende Direktive effektiv alle Eingabeköpfe, die mit "X-Hidden-" beginnen:

     more_clear_input_headers 'X-Hidden-*';

Einschränkungen

  • Im Gegensatz zum Standard- headers Modul kümmert sich dieses Modul nicht automatisch um die Einschränkung zwischen den Expires, Cache-Control und Last-Modified Headern. Sie müssen dies selbst richtig einstellen oder das headers Modul zusammen mit diesem Modul verwenden.
  • Sie können den Connection Antwortheader mit diesem Modul nicht entfernen, da der Connection Antwortheader vom Standard ngx_http_header_filter_module im Nginx-Kern generiert wird, dessen Ausgabeheader-Filter immer nach dem Filter dieses Moduls ausgeführt wird. Der einzige Weg, den Connection Header tatsächlich zu entfernen, besteht darin, den Nginx-Kern zu patchen, d. h. die C-Funktion ngx_http_header_filter in der Datei src/http/ngx_http_header_filter_module.c zu bearbeiten.

Änderungen

Die Änderungen jeder Version dieses Moduls können aus den Änderungsprotokollen des OpenResty-Bundles abgerufen werden:

http://openresty.org/#Changes

Test Suite

Dieses Modul wird mit einer Perl-gesteuerten Test-Suite geliefert. Die Testfälle sind ebenfalls deklarativ. Dank des Test::Nginx Moduls in der Perl-Welt.

Um es auf Ihrer Seite auszuführen:

 $ PATH=/path/to/your/nginx-with-headers-more-module:$PATH prove -r t

Um die Test-Suite mit Valgrinds Memcheck auszuführen, verwenden Sie die folgenden Befehle:

 $ export PATH=/path/to/your/nginx-with-headers-more-module:$PATH
 $ TEST_NGINX_USE_VALGRIND=1 prove -r t

Sie müssen alle Nginx-Prozesse beenden, bevor Sie die Test-Suite ausführen, wenn Sie die Nginx-Server-Binärdatei geändert haben.

Da ein einzelner Nginx-Server (standardmäßig localhost:1984) über alle Testskripte (.t Dateien) verwendet wird, ist es bedeutungslos, die Test-Suite parallel auszuführen, indem Sie -jN beim Aufrufen des prove-Dienstprogramms angeben.

Einige Teile der Test-Suite erfordern auch, dass die Module proxy, rewrite und echo beim Erstellen von Nginx aktiviert sind.

Siehe auch

GitHub

Sie finden möglicherweise zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-headers-more.