Перейти к содержанию

headers-more: Динамический модуль заголовков NGINX

Установка на Debian/Ubuntu

Эти документы применимы к APT пакету nginx-module-headers-more, предоставляемому репозиторием GetPageSpeed Extras.

  1. Настройте репозиторий APT, как описано в настройке репозитория APT.
  2. Установите модуль:
sudo apt-get update
sudo apt-get install nginx-module-headers-more
Показать дистрибутивы и архитектуры 
| Distro   | Suite             | Component   | Architectures   |
|----------|-------------------|-------------|-----------------|
| debian   | bookworm          | main        | amd64, arm64    |
| debian   | bookworm-mainline | main        | amd64, arm64    |
| debian   | trixie            | main        | amd64, arm64    |
| debian   | trixie-mainline   | main        | amd64, arm64    |
| ubuntu   | focal             | main        | amd64, arm64    |
| ubuntu   | focal-mainline    | main        | amd64, arm64    |
| ubuntu   | jammy             | main        | amd64, arm64    |
| ubuntu   | jammy-mainline    | main        | amd64, arm64    |
| ubuntu   | noble             | main        | amd64, arm64    |
| ubuntu   | noble-mainline    | main        | amd64, arm64    |

ngx_headers_more - Устанавливайте и очищайте входные и выходные заголовки... больше, чем просто "добавить"!

Аннотация

 # устанавливаем заголовок сервера
 more_set_headers 'Server: my-server';

 # устанавливаем и очищаем выходные заголовки
 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';

     # ваша конфигурация proxy_pass/memcached_pass/или любая другая конфигурация здесь...
 }

 # устанавливаем выходные заголовки
 location /type {
     more_set_headers 'Content-Type: text/plain';
     # ...
 }

 # устанавливаем входные заголовки
 location /foo {
     set $my_host 'my dog';
     more_set_input_headers 'Host: $my_host';
     more_set_input_headers -t 'text/plain' 'X-Foo: bah';

     # теперь $host и $http_host имеют новые значения...
     # ...
 }

 # заменяем входной заголовок X-Foo *только* если он уже существует
 more_set_input_headers -r 'X-Foo: howdy';

Описание

Этот модуль позволяет добавлять, устанавливать или очищать любые выходные или входные заголовки, которые вы укажете.

Это расширенная версия стандартного модуля заголовков, поскольку он предоставляет больше утилит, например, сброс или очистку "встроенных заголовков", таких как Content-Type, Content-Length и Server.

Он также позволяет вам указать необязательный критерий кода статуса HTTP, используя опцию -s и необязательный критерий типа содержимого, используя опцию -t, при изменении выходных заголовков с помощью директив more_set_headers и more_clear_headers. Например,

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

Вы также можете указать несколько MIME-типов для фильтрации в одной опции -t. Например,

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

Никогда не используйте другие параметры, такие как charset=utf-8 в значениях опции -t; они не будут работать так, как вы ожидаете.

Входные заголовки также могут быть изменены. Например

 location /foo {
     more_set_input_headers 'Host: foo' 'User-Agent: faked';
     # теперь $host, $http_host, $user_agent и
     #   $http_user_agent все имеют свои новые значения.
 }

Опция -t также доступна в директивах more_set_input_headers и more_clear_input_headers (для фильтрации заголовков запроса), в то время как опция -s не разрешена.

В отличие от стандартного модуля заголовков, директивы этого модуля по умолчанию применяются ко всем кодам статуса, включая 4xx и 5xx.

Директивы

more_set_headers

синтаксис: more_set_headers [-t <список-content-type>]... [-s <список-кодов статуса>]... <новый-заголовок>...

по умолчанию: нет

контекст: http, server, location, location if

фаза: output-header-filter

Заменяет (если есть) или добавляет (если нет) указанные выходные заголовки, когда код статуса ответа соответствует кодам, указанным с помощью опции -s И тип содержимого ответа соответствует типам, указанным с помощью опции -t.

Если либо -s, либо -t не указано или имеет пустое значение, то совпадение не требуется. Следовательно, следующая директива устанавливает выходной заголовок Server на пользовательское значение для любого кода статуса и любого типа содержимого:

   more_set_headers    "Server: my_server";

Существующие ответные заголовки с тем же именем всегда переопределяются. Если вы хотите добавлять заголовки поэтапно, используйте стандартную директиву add_header.

Одна директива может установить/добавить несколько выходных заголовков. Например

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

Различные повторения опций допускаются в одной директиве. Их значения будут объединены. Например

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

эквивалентно

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

Новый заголовок должен быть одним из следующих форм:

  1. Имя: Значение
  2. Имя:
  3. Имя

Последние два фактически очищают значение заголовка Имя.

Переменные Nginx разрешены в значениях заголовков. Например:

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

Но переменные не будут работать в ключах заголовков по причинам производительности.

Несколько директив установки/очистки заголовка допускаются в одном location, и они выполняются последовательно.

Директивы, унаследованные от верхнего уровня (например, блока http или серверов), выполняются перед директивами в блоке location.

Обратите внимание, что хотя more_set_headers разрешен в блоках location if, он не разрешен в блоках server if, как в

   ?  # Это НЕЛЬЗЯ!
   ?  server {
   ?      if ($args ~ 'download') {
   ?          more_set_headers 'Foo: Bar';
   ?      }
   ?      ...
   ?  }

За кулисами использование этой директивы и её друзей more_clear_headers (лениво) зарегистрирует фильтр заголовка ouput, который модифицирует r->headers_out так, как вы укажете.

more_clear_headers

синтаксис: more_clear_headers [-t <список-content-type>]... [-s <список-кодов статуса>]... <новый-заголовок>...

по умолчанию: нет

контекст: http, server, location, location if

фаза: output-header-filter

Очищает указанные выходные заголовки.

На самом деле,

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

точно эквивалентно

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

или

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

См. more_set_headers для получения дополнительных деталей.

Символ подстановки * также может использоваться в конце имени заголовка для указания шаблона. Например, следующая директива фактически очищает любые выходные заголовки, начинающиеся с "X-Hidden-":

 more_clear_headers 'X-Hidden-*';

Поддержка подстановочного знака * была впервые введена в v0.09.

more_set_input_headers

синтаксис: more_set_input_headers [-r] [-t <список-content-type>]... <новый-заголовок>...

по умолчанию: нет

контекст: http, server, location, location if

фаза: rewrite tail

По сути, это то же самое, что и more_set_headers, за исключением того, что это работает с входными заголовками (или заголовками запроса), и поддерживает только опцию -t.

Обратите внимание, что использование опции -t в этой директиве означает фильтрацию по заголовку Content-Type запроса, а не по заголовку ответа.

За кулисами использование этой директивы и её друга more_clear_input_headers (лениво) зарегистрирует обработчик rewrite phase, который модифицирует r->headers_in так, как вы укажете. Обратите внимание, что он всегда выполняется в конце фазы rewrite, чтобы он работал после стандартного модуля повторной записи и работал в подпроцессах также.

Если указана опция -r, то заголовки будут заменены на новые значения только если они уже существуют.

more_clear_input_headers

синтаксис: more_clear_input_headers [-t <список-content-type>]... <новый-заголовок>...

по умолчанию: нет

контекст: http, server, location, location if

фаза: rewrite tail

Очищает указанные входные заголовки.

На самом деле,

    more_clear_input_headers -t 'text/plain' Foo Baz;

точно эквивалентно

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

или

    more_set_input_headers -t 'text/plain' Foo Baz

Чтобы удалить заголовки запросов "Foo" и "Baz" для всех входящих запросов независимо от типа содержимого, мы можем написать

    more_clear_input_headers "Foo" "Baz";

См. more_set_input_headers для получения дополнительных деталей.

Символ подстановки * также может использоваться в конце имени заголовка для указания шаблона. Например, следующая директива фактически очищает любые входные заголовки, начинающиеся с "X-Hidden-":

     more_clear_input_headers 'X-Hidden-*';

Ограничения

  • В отличие от стандартного модуля заголовков, этот модуль не заботится автоматически о взаимосвязи между заголовками Expires, Cache-Control и Last-Modified. Вам нужно сделать это самостоятельно или использовать модуль headers вместе с этим модулем.
  • Вы не можете удалить заголовок ответа Connection, используя этот модуль, потому что заголовок ответа Connection создается стандартным ngx_http_header_filter_module в ядре Nginx, фильтр заголовков которого всегда выполняется после фильтра этого модуля. Единственный способ фактически удалить заголовок Connection - это сделать патч для ядра Nginx, то есть отредактировать функцию на C ngx_http_header_filter в файле src/http/ngx_http_header_filter_module.c.

Изменения

Изменения каждой версии этого модуля можно получить из журналов изменений пакета OpenResty:

http://openresty.org/#Changes

Тестовый набор

Этот модуль поставляется с тестовым набором, управляемым Perl. тестовые случаи также являются декларативными. Благодаря Test::Nginx в мире Perl.

Чтобы запустить его на вашей стороне:

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

Чтобы запустить тестовый набор с помощью memcheck в valgrind, используйте следующие команды:

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

Вам необходимо завершить все процессы Nginx перед запуском тестового набора, если вы изменили двоичный файл сервера Nginx.

Поскольку для выполнения всех тестовых скриптов (файлов .t) используется один сервер nginx (по умолчанию, localhost:1984), имеет смысл запускать тестовый набор параллельно, указывая -jN, когда вы вызываете утилиту prove.

Некоторые части тестового набора требуют включения модулей proxy, rewrite и echo при сборке Nginx.

Смотрите также