headers-more: Módulo dinámico de NGINX Headers More

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:

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

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 y Amazon Linux 2

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

Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:

load_module modules/ngx_http_headers_more_filter_module.so;

Este documento describe nginx-module-headers-more v0.33 lanzado el 28 de junio de 2022.

 # establecer el encabezado de salida Server
 more_set_headers 'Server: my-server';

 # establecer y limpiar encabezados de salida
 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';

     # tu proxy_pass/memcached_pass/o cualquier otra configuración va aquí...
 }

 # establecer encabezados de salida
 location /type {
     more_set_headers 'Content-Type: text/plain';
     # ...
 }

 # establecer encabezados de entrada
 location /foo {
     set $my_host 'my dog';
     more_set_input_headers 'Host: $my_host';
     more_set_input_headers -t 'text/plain' 'X-Foo: bah';

     # ahora $host y $http_host tienen sus nuevos valores...
     # ...
 }

 # reemplazar el encabezado de entrada X-Foo *solo* si ya existe
 more_set_input_headers -r 'X-Foo: howdy';

Descripción

Este módulo te permite agregar, establecer o limpiar cualquier encabezado de salida o entrada que especifiques.

Esta es una versión mejorada del módulo estándar headers porque proporciona más utilidades como restablecer o limpiar "encabezados integrados" como Content-Type, Content-Length y Server.

También te permite especificar un código de estado HTTP opcional utilizando la opción -s y un criterio de tipo de contenido opcional utilizando la opción -t mientras modificas los encabezados de salida con las directivas more_set_headers y more_clear_headers. Por ejemplo,

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

También puedes especificar múltiples tipos MIME para filtrar en una sola opción -t. Por ejemplo,

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

Nunca uses otros parámetros como charset=utf-8 en los valores de la opción -t; no funcionarán como esperas.

Los encabezados de entrada también pueden ser modificados. Por ejemplo

 location /foo {
     more_set_input_headers 'Host: foo' 'User-Agent: faked';
     # ahora $host, $http_host, $user_agent, y
     #   $http_user_agent todos tienen sus nuevos valores.
 }

La opción -t también está disponible en las directivas more_set_input_headers y more_clear_input_headers (para filtrado de encabezados de solicitud) mientras que la opción -s no está permitida.

A diferencia del módulo estándar headers, las directivas de este módulo se aplicarán por defecto a todos los códigos de estado, incluyendo 4xx y 5xx.

Directivas

more_set_headers

sintaxis: more_set_headers [-t <lista de tipos de contenido>]... [-s <lista de códigos de estado>]... <nuevo-encabezado>...

predeterminado: no

contexto: http, server, location, location if

fase: filtro-de-encabezado-salida

Reemplaza (si hay) o agrega (si no hay) los encabezados de salida especificados cuando el código de estado de respuesta coincide con los códigos especificados por la opción -s Y el tipo de contenido de respuesta coincide con los tipos especificados por la opción -t.

Si no se especifica -s o -t, o si tiene un valor de lista vacío, entonces no se requiere coincidencia. Por lo tanto, la siguiente directiva establece el encabezado de salida Server al valor personalizado para cualquier código de estado y cualquier tipo de contenido:

   more_set_headers    "Server: my_server";

Los encabezados de respuesta existentes con el mismo nombre siempre se sobrescriben. Si deseas agregar encabezados de manera incremental, utiliza la directiva estándar add_header en su lugar.

Una sola directiva puede establecer/agregar múltiples encabezados de salida. Por ejemplo

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

Se permiten múltiples ocurrencias de las opciones en una sola directiva. Sus valores se fusionarán. Por ejemplo

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

es equivalente a

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

El nuevo encabezado debe ser uno de los siguientes formatos:

Nombre: Valor
Nombre:
Nombre

Los dos últimos efectivamente limpian el valor del encabezado Nombre.

Se permiten variables de Nginx en los valores de los encabezados. Por ejemplo:

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

Pero las variables no funcionarán en las claves de los encabezados debido a consideraciones de rendimiento.

Se permiten múltiples directivas de establecer/limpiar encabezados en una sola ubicación, y se ejecutan secuencialmente.

Las directivas heredadas de un ámbito superior (por ejemplo, bloque http o bloques de servidor) se ejecutan antes de las directivas en el bloque de ubicación.

Ten en cuenta que aunque more_set_headers está permitido en bloques if de location, no está permitido en los bloques if de server, como en

   ?  # ¡Esto NO está permitido!
   ?  server {
   ?      if ($args ~ 'download') {
   ?          more_set_headers 'Foo: Bar';
   ?      }
   ?      ...
   ?  }

Detrás de escena, el uso de esta directiva y su amiga more_clear_headers registrará (de manera perezosa) un filtro de encabezado de salida que modifica r->headers_out de la manera que especifiques.

more_clear_headers

sintaxis: more_clear_headers [-t <lista de tipos de contenido>]... [-s <lista de códigos de estado>]... <nuevo-encabezado>...

predeterminado: no

contexto: http, server, location, location if

fase: filtro-de-encabezado-salida

Limpia los encabezados de salida especificados.

De hecho,

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

es exactamente equivalente a

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

o

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

Consulta more_set_headers para más detalles.

El carácter comodín, *, también se puede usar al final del nombre del encabezado para especificar un patrón. Por ejemplo, la siguiente directiva limpia efectivamente cualquier encabezado de salida que comience con "X-Hidden-":

 more_clear_headers 'X-Hidden-*';

El soporte para el comodín * se introdujo por primera vez en v0.09.

more_set_input_headers

sintaxis: more_set_input_headers [-r] [-t <lista de tipos de contenido>]... <nuevo-encabezado>...

predeterminado: no

contexto: http, server, location, location if

fase: cola de reescritura

Muy similar a more_set_headers excepto que opera en encabezados de entrada (o encabezados de solicitud) y solo admite la opción -t.

Ten en cuenta que usar la opción -t en esta directiva significa filtrar por el encabezado de solicitud Content-Type, en lugar del encabezado de respuesta.

Detrás de escena, el uso de esta directiva y su amiga more_clear_input_headers registrará (de manera perezosa) un controlador de fase de reescritura que modifica r->headers_in de la manera que especifiques. Ten en cuenta que siempre se ejecuta al final de la fase de reescritura, de modo que se ejecuta después del módulo de reescritura estándar y funciona también en subsolicitudes.

Si se especifica la opción -r, entonces los encabezados se reemplazarán por los nuevos valores solo si ya existen.

more_clear_input_headers

sintaxis: more_clear_input_headers [-t <lista de tipos de contenido>]... <nuevo-encabezado>...

predeterminado: no

contexto: http, server, location, location if

fase: cola de reescritura

Limpia los encabezados de entrada especificados.

De hecho,

    more_clear_input_headers -t 'text/plain' Foo Baz;

es exactamente equivalente a

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

o

    more_set_input_headers -t 'text/plain' Foo Baz

Para eliminar los encabezados de solicitud "Foo" y "Baz" para todas las solicitudes entrantes independientemente del tipo de contenido, podemos escribir

    more_clear_input_headers "Foo" "Baz";

Consulta more_set_input_headers para más detalles.

El carácter comodín, *, también se puede usar al final del nombre del encabezado para especificar un patrón. Por ejemplo, la siguiente directiva limpia efectivamente cualquier encabezado de entrada que comience con "X-Hidden-":

     more_clear_input_headers 'X-Hidden-*';

Limitaciones

A diferencia del módulo estándar headers, este módulo no se encarga automáticamente de la restricción entre los encabezados Expires, Cache-Control y Last-Modified. Debes configurarlos correctamente tú mismo o usar el módulo headers junto con este módulo.
No puedes eliminar el encabezado de respuesta Connection usando este módulo porque el encabezado de respuesta Connection es generado por el módulo estándar ngx_http_header_filter_module en el núcleo de Nginx, cuyo filtro de encabezado de salida se ejecuta siempre después del filtro de este módulo. La única forma de eliminar realmente el encabezado Connection es parchear el núcleo de Nginx, es decir, editar la función C ngx_http_header_filter en el archivo src/http/ngx_http_header_filter_module.c.

Cambios

Los cambios de cada versión de este módulo se pueden obtener de los registros de cambios del paquete OpenResty:

http://openresty.org/#Changes

Suite de Pruebas

Este módulo viene con una suite de pruebas impulsada por Perl. Los casos de prueba son también declarativos. Gracias al módulo Test::Nginx en el mundo de Perl.

Para ejecutarlo en tu lado:

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

Para ejecutar la suite de pruebas con memcheck de valgrind, usa los siguientes comandos:

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

Necesitas terminar cualquier proceso de Nginx antes de ejecutar la suite de pruebas si has cambiado el binario del servidor Nginx.

Debido a que se utiliza un solo servidor nginx (por defecto, localhost:1984) en todos los scripts de prueba (.t), no tiene sentido ejecutar la suite de pruebas en paralelo especificando -jN al invocar la utilidad prove.

Algunas partes de la suite de pruebas requieren que los módulos proxy, rewrite y echo también estén habilitados al construir Nginx.

Ver También

El hilo original en la lista de correo de Nginx que inspira el desarrollo de este módulo: "Una pregunta sobre la replicación de add_header".
El hilo de anuncio original en la lista de correo de Nginx: "El módulo "headers_more": Establecer y limpiar encabezados de salida... ¡más que 'add'!".
La entrada de blog original sobre el desarrollo inicial de este módulo.
El módulo echo para pruebas automatizadas del módulo Nginx.
El módulo estándar headers.

GitHub

Puedes encontrar consejos de configuración adicionales y documentación para este módulo en el repositorio de GitHub para nginx-module-headers-more.