Aller au contenu

headers-more: Module dynamique NGINX Headers More

Installation

Vous pouvez installer ce module dans n'importe quelle distribution basée sur RHEL, y compris, 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-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

Activez le module en ajoutant ce qui suit en haut de /etc/nginx/nginx.conf :

load_module modules/ngx_http_headers_more_filter_module.so;

Ce document décrit nginx-module-headers-more v0.33 publié le 28 juin 2022.

 # définir l'en-tête de sortie Server
 more_set_headers 'Server: my-server';

 # définir et effacer les en-têtes de sortie
 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';

     # votre proxy_pass/memcached_pass/ou toute autre configuration va ici...
 }

 # définir les en-têtes de sortie
 location /type {
     more_set_headers 'Content-Type: text/plain';
     # ...
 }

 # définir les en-têtes d'entrée
 location /foo {
     set $my_host 'my dog';
     more_set_input_headers 'Host: $my_host';
     more_set_input_headers -t 'text/plain' 'X-Foo: bah';

     # maintenant $host et $http_host ont leurs nouvelles valeurs...
     # ...
 }

 # remplacer l'en-tête d'entrée X-Foo *uniquement* s'il existe déjà
 more_set_input_headers -r 'X-Foo: howdy';

Description

Ce module vous permet d'ajouter, de définir ou d'effacer n'importe quel en-tête de sortie ou d'entrée que vous spécifiez.

C'est une version améliorée du module standard headers car il fournit plus d'utilitaires comme la réinitialisation ou l'effacement des "en-têtes intégrés" comme Content-Type, Content-Length et Server.

Il vous permet également de spécifier un code d'état HTTP optionnel en utilisant l'option -s et un critère de type de contenu optionnel en utilisant l'option -t lors de la modification des en-têtes de sortie avec les directives more_set_headers et more_clear_headers. Par exemple,

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

Vous pouvez également spécifier plusieurs types MIME à filtrer dans une seule option -t. Par exemple,

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

N'utilisez jamais d'autres paramètres comme charset=utf-8 dans les valeurs de l'option -t ; ils ne fonctionneront pas comme vous vous y attendez.

Les en-têtes d'entrée peuvent également être modifiés. Par exemple

 location /foo {
     more_set_input_headers 'Host: foo' 'User-Agent: faked';
     # maintenant $host, $http_host, $user_agent, et
     #   $http_user_agent ont tous leurs nouvelles valeurs.
 }

L'option -t est également disponible dans les directives more_set_input_headers et more_clear_input_headers (pour le filtrage des en-têtes de requête) tandis que l'option -s n'est pas autorisée.

Contrairement au module standard headers, les directives de ce module s'appliqueront par défaut à tous les codes d'état, y compris 4xx et 5xx.

Directives

more_set_headers

syntaxe : more_set_headers [-t <liste de types de contenu>]... [-s <liste de codes d'état>]... <nouvel en-tête>...

par défaut : non

contexte : http, server, location, location if

phase : filtre d'en-tête de sortie

Remplace (s'il y en a) ou ajoute (s'il n'y en a pas) les en-têtes de sortie spécifiés lorsque le code d'état de la réponse correspond aux codes spécifiés par l'option -s ET le type de contenu de la réponse correspond aux types spécifiés par l'option -t.

Si -s ou -t n'est pas spécifié ou a une valeur de liste vide, alors aucune correspondance n'est requise. Par conséquent, la directive suivante définit l'en-tête de sortie Server à la valeur personnalisée pour tout code d'état et tout type de contenu :

   more_set_headers    "Server: my_server";

Les en-têtes de réponse existants ayant le même nom sont toujours remplacés. Si vous souhaitez ajouter des en-têtes de manière incrémentielle, utilisez la directive standard add_header.

Une seule directive peut définir/ajouter plusieurs en-têtes de sortie. Par exemple

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

Plusieurs occurrences des options sont autorisées dans une seule directive. Leurs valeurs seront fusionnées. Par exemple

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

est équivalent à

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

Le nouvel en-tête doit être l'une des formes suivantes :

  1. Nom: Valeur
  2. Nom:
  3. Nom

Les deux dernières effacent effectivement la valeur de l'en-tête Nom.

Les variables Nginx sont autorisées dans les valeurs d'en-tête. Par exemple :

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

Mais les variables ne fonctionneront pas dans les clés d'en-tête pour des raisons de performance.

Plusieurs directives de définition/effacement d'en-tête sont autorisées dans une seule location, et elles sont exécutées séquentiellement.

Les directives héritées d'un niveau supérieur (par exemple, bloc http ou blocs server) sont exécutées avant les directives dans le bloc location.

Notez que bien que more_set_headers soit autorisé dans les blocs location if, il n'est pas autorisé dans les blocs server if, comme dans

   ?  # Ceci n'est PAS autorisé !
   ?  server {
   ?      if ($args ~ 'download') {
   ?          more_set_headers 'Foo: Bar';
   ?      }
   ?      ...
   ?  }

En arrière-plan, l'utilisation de cette directive et de son amie more_clear_headers enregistrera (paresseusement) un filtre d'en-tête de sortie qui modifie r->headers_out de la manière que vous spécifiez.

more_clear_headers

syntaxe : more_clear_headers [-t <liste de types de contenu>]... [-s <liste de codes d'état>]... <nouvel en-tête>...

par défaut : non

contexte : http, server, location, location if

phase : filtre d'en-tête de sortie

Efface les en-têtes de sortie spécifiés.

En fait,

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

est exactement équivalent à

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

ou

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

Voir more_set_headers pour plus de détails.

Le caractère générique, *, peut également être utilisé à la fin du nom de l'en-tête pour spécifier un motif. Par exemple, la directive suivante efface effectivement tous les en-têtes de sortie commençant par "X-Hidden-" :

 more_clear_headers 'X-Hidden-*';

Le support du caractère générique * a été introduit pour la première fois dans v0.09.

more_set_input_headers

syntaxe : more_set_input_headers [-r] [-t <liste de types de contenu>]... <nouvel en-tête>...

par défaut : non

contexte : http, server, location, location if

phase : queue de réécriture

Très similaire à more_set_headers sauf qu'il opère sur les en-têtes d'entrée (ou en-têtes de requête) et ne prend en charge que l'option -t.

Notez que l'utilisation de l'option -t dans cette directive signifie filtrer par l'en-tête de requête Content-Type, plutôt que l'en-tête de réponse.

En arrière-plan, l'utilisation de cette directive et de son amie more_clear_input_headers enregistrera (paresseusement) un gestionnaire de phase de réécriture qui modifie r->headers_in de la manière que vous spécifiez. Notez qu'il s'exécute toujours à la fin de la phase de réécriture afin qu'il s'exécute après le module de réécriture standard rewrite module et fonctionne également dans les sous-requêtes.

Si l'option -r est spécifiée, alors les en-têtes seront remplacés par les nouvelles valeurs uniquement s'ils existent déjà.

more_clear_input_headers

syntaxe : more_clear_input_headers [-t <liste de types de contenu>]... <nouvel en-tête>...

par défaut : non

contexte : http, server, location, location if

phase : queue de réécriture

Efface les en-têtes d'entrée spécifiés.

En fait,

    more_clear_input_headers -t 'text/plain' Foo Baz;

est exactement équivalent à

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

ou

    more_set_input_headers -t 'text/plain' Foo Baz

Pour supprimer les en-têtes de requête "Foo" et "Baz" pour toutes les requêtes entrantes, quel que soit le type de contenu, nous pouvons écrire

    more_clear_input_headers "Foo" "Baz";

Voir more_set_input_headers pour plus de détails.

Le caractère générique, *, peut également être utilisé à la fin du nom de l'en-tête pour spécifier un motif. Par exemple, la directive suivante efface effectivement tous les en-têtes d'entrée commençant par "X-Hidden-" :

     more_clear_input_headers 'X-Hidden-*';

Limitations

  • Contrairement au module standard headers, ce module ne prend pas automatiquement en charge la contrainte entre les en-têtes Expires, Cache-Control et Last-Modified. Vous devez les gérer vous-même ou utiliser le module headers avec ce module.
  • Vous ne pouvez pas supprimer l'en-tête de réponse Connection à l'aide de ce module car l'en-tête de réponse Connection est généré par le module standard ngx_http_header_filter_module dans le cœur de Nginx, dont le filtre d'en-tête de sortie s'exécute toujours après le filtre de ce module. La seule façon de réellement supprimer l'en-tête Connection est de patcher le cœur de Nginx, c'est-à-dire d'éditer la fonction C ngx_http_header_filter dans le fichier src/http/ngx_http_header_filter_module.c.

Changements

Les changements de chaque version de ce module peuvent être obtenus à partir des journaux de modifications du bundle OpenResty :

http://openresty.org/#Changes

Suite de tests

Ce module est livré avec une suite de tests pilotée par Perl. Les cas de test sont également déclaratifs. Merci au module Test::Nginx dans le monde Perl.

Pour l'exécuter de votre côté :

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

Pour exécuter la suite de tests avec memcheck de valgrind, utilisez les commandes suivantes :

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

Vous devez terminer tous les processus Nginx avant d'exécuter la suite de tests si vous avez modifié le binaire du serveur Nginx.

Comme un seul serveur nginx (par défaut, localhost:1984) est utilisé dans tous les scripts de test (.t fichiers), il est inutile d'exécuter la suite de tests en parallèle en spécifiant -jN lors de l'invocation de l'utilitaire prove.

Certaines parties de la suite de tests nécessitent également que les modules proxy, rewrite et echo soient activés lors de la construction de Nginx.

Voir aussi

GitHub

Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-headers-more.