Pular para conteúdo

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

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

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

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_headers_more_filter_module.so;

Este documento descreve o nginx-module-headers-more v0.33 lançado em 28 de junho de 2022.

 # define o cabeçalho de saída Server
 more_set_headers 'Server: my-server';

 # define e limpa cabeçalhos de saída
 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';

     # sua configuração proxy_pass/memcached_pass ou qualquer outra vai aqui...
 }

 # define cabeçalhos de saída
 location /type {
     more_set_headers 'Content-Type: text/plain';
     # ...
 }

 # define cabeçalhos 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';

     # agora $host e $http_host têm seus novos valores...
     # ...
 }

 # substitui o cabeçalho de entrada X-Foo *somente* se já existir
 more_set_input_headers -r 'X-Foo: howdy';

Descrição

Este módulo permite que você adicione, defina ou limpe qualquer cabeçalho de saída ou de entrada que você especificar.

Esta é uma versão aprimorada do módulo padrão headers porque fornece mais utilitários, como redefinir ou limpar "cabeçalhos embutidos" como Content-Type, Content-Length e Server.

Ele também permite que você especifique um código de status HTTP opcional usando a opção -s e um critério de tipo de conteúdo opcional usando a opção -t ao modificar os cabeçalhos de saída com as diretivas more_set_headers e more_clear_headers. Por exemplo,

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

Você também pode especificar múltiplos tipos MIME para filtrar em uma única opção -t. Por exemplo,

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

Nunca use outros parâmetros como charset=utf-8 nos valores da opção -t; eles não funcionarão como você espera.

Os cabeçalhos de entrada também podem ser modificados. Por exemplo

 location /foo {
     more_set_input_headers 'Host: foo' 'User-Agent: faked';
     # agora $host, $http_host, $user_agent, e
     #   $http_user_agent têm todos seus novos valores.
 }

A opção -t também está disponível nas diretivas more_set_input_headers e more_clear_input_headers (para filtragem de cabeçalhos de requisição), enquanto a opção -s não é permitida.

Ao contrário do módulo padrão headers, as diretivas deste módulo, por padrão, se aplicam a todos os códigos de status, incluindo 4xx e 5xx.

Diretivas

more_set_headers

sintaxe: more_set_headers [-t <lista de tipos de conteúdo>]... [-s <lista de códigos de status>]... <novo-cabeçalho>...

padrão: não

contexto: http, server, location, location if

fase: output-header-filter

Substitui (se houver) ou adiciona (se não houver) os cabeçalhos de saída especificados quando o código de status da resposta corresponde aos códigos especificados pela opção -s E o tipo de conteúdo da resposta corresponde aos tipos especificados pela opção -t.

Se -s ou -t não forem especificados ou tiverem um valor de lista vazio, então nenhuma correspondência é necessária. Portanto, a seguinte diretiva define o cabeçalho de saída Server para o valor personalizado para qualquer código de status e qualquer tipo de conteúdo:

   more_set_headers    "Server: my_server";

Os cabeçalhos de resposta existentes com o mesmo nome são sempre sobrescritos. Se você quiser adicionar cabeçalhos incrementalmente, use a diretiva padrão add_header.

Uma única diretiva pode definir/adicionar múltiplos cabeçalhos de saída. Por exemplo

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

Múltiplas ocorrências das opções são permitidas em uma única diretiva. Seus valores serão mesclados. Por exemplo

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

é equivalente a

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

O novo cabeçalho deve estar em uma das formas:

  1. Nome: Valor
  2. Nome:
  3. Nome

Os dois últimos efetivamente limpam o valor do cabeçalho Nome.

Variáveis do Nginx são permitidas nos valores dos cabeçalhos. Por exemplo:

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

Mas variáveis não funcionarão nas chaves dos cabeçalhos devido a considerações de desempenho.

Múltiplas diretivas de set/clear de cabeçalho são permitidas em uma única localização, e elas são executadas sequencialmente.

Diretivas herdadas de um escopo de nível superior (por exemplo, bloco http ou blocos de servidor) são executadas antes das diretivas no bloco de localização.

Observe que, embora more_set_headers seja permitido em blocos location if, ele não é permitido em blocos server if, como em

   ?  # Isso NÃO é permitido!
   ?  server {
   ?      if ($args ~ 'download') {
   ?          more_set_headers 'Foo: Bar';
   ?      }
   ?      ...
   ?  }

Nos bastidores, o uso desta diretiva e sua amiga more_clear_headers registrará (de forma preguiçosa) um filtro de cabeçalho de saída que modifica r->headers_out da maneira que você especificar.

more_clear_headers

sintaxe: more_clear_headers [-t <lista de tipos de conteúdo>]... [-s <lista de códigos de status>]... <novo-cabeçalho>...

padrão: não

contexto: http, server, location, location if

fase: output-header-filter

Limpa os cabeçalhos de saída especificados.

Na verdade,

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

é exatamente equivalente a

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

ou

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

Veja more_set_headers para mais detalhes.

O caractere curinga, *, também pode ser usado no final do nome do cabeçalho para especificar um padrão. Por exemplo, a seguinte diretiva efetivamente limpa qualquer cabeçalho de saída que comece com "X-Hidden-":

 more_clear_headers 'X-Hidden-*';

O suporte ao curinga * foi introduzido pela primeira vez na v0.09.

more_set_input_headers

sintaxe: more_set_input_headers [-r] [-t <lista de tipos de conteúdo>]... <novo-cabeçalho>...

padrão: não

contexto: http, server, location, location if

fase: rewrite tail

Muito parecido com more_set_headers, exceto que opera em cabeçalhos de entrada (ou cabeçalhos de requisição) e suporta apenas a opção -t.

Observe que usar a opção -t nesta diretiva significa filtrar pelo cabeçalho de requisição Content-Type, em vez do cabeçalho de resposta.

Nos bastidores, o uso desta diretiva e sua amiga more_clear_input_headers registrará (de forma preguiçosa) um manipulador da fase rewrite que modifica r->headers_in da maneira que você especificar. Observe que ele sempre é executado no final da fase rewrite, de modo que ele é executado após o módulo padrão rewrite e funciona em subrequisições também.

Se a opção -r for especificada, então os cabeçalhos serão substituídos pelos novos valores somente se já existirem.

more_clear_input_headers

sintaxe: more_clear_input_headers [-t <lista de tipos de conteúdo>]... <novo-cabeçalho>...

padrão: não

contexto: http, server, location, location if

fase: rewrite tail

Limpa os cabeçalhos de entrada especificados.

Na verdade,

    more_clear_input_headers -t 'text/plain' Foo Baz;

é exatamente equivalente a

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

ou

    more_set_input_headers -t 'text/plain' Foo Baz

Para remover os cabeçalhos de requisição "Foo" e "Baz" para todas as requisições recebidas, independentemente do tipo de conteúdo, podemos escrever

    more_clear_input_headers "Foo" "Baz";

Veja more_set_input_headers para mais detalhes.

O caractere curinga, *, também pode ser usado no final do nome do cabeçalho para especificar um padrão. Por exemplo, a seguinte diretiva efetivamente limpa qualquer cabeçalho de entrada que comece com "X-Hidden-":

     more_clear_input_headers 'X-Hidden-*';

Limitações

  • Ao contrário do módulo padrão headers, este módulo não cuida automaticamente da restrição entre os cabeçalhos Expires, Cache-Control e Last-Modified. Você deve configurá-los corretamente ou usar o módulo headers junto com este módulo.
  • Você não pode remover o cabeçalho de resposta Connection usando este módulo porque o cabeçalho de resposta Connection é gerado pelo padrão ngx_http_header_filter_module no núcleo do Nginx, cujo filtro de cabeçalho de saída é executado sempre após o filtro deste módulo. A única maneira de realmente remover o cabeçalho Connection é patchar o núcleo do Nginx, ou seja, editar a função C ngx_http_header_filter no arquivo src/http/ngx_http_header_filter_module.c.

Mudanças

As mudanças de cada versão deste módulo podem ser obtidas nos logs de alterações do pacote OpenResty:

http://openresty.org/#Changes

Conjunto de Testes

Este módulo vem com um conjunto de testes dirigido por Perl. Os casos de teste também são declarativos. Graças ao módulo Test::Nginx no mundo Perl.

Para executá-lo do seu lado:

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

Para executar o conjunto de testes com o memcheck do valgrind, use os seguintes comandos:

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

Você precisa encerrar qualquer processo Nginx antes de executar o conjunto de testes se você tiver alterado o binário do servidor Nginx.

Como um único servidor nginx (por padrão, localhost:1984) é usado em todos os scripts de teste (.t), não faz sentido executar o conjunto de testes em paralelo especificando -jN ao invocar a utilidade prove.

Algumas partes do conjunto de testes requerem que os módulos proxy, rewrite, e echo também estejam habilitados ao construir o Nginx.

Veja Também

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório GitHub para nginx-module-headers-more.