Apache: Модуль Apache mod

RU EN

Пункт 144. Модуль Apache mod_headers

Этот модуль предоставляет директивы для управления и изменения заголовков запросов и ответов HTTP. Заголовки можно объединять, заменять или удалять.

Порядок обработки

Предоставленные директивы mod_headers могут встречаться практически в любом месте конфигурации сервера и могут быть ограничены по объему путем включения их в разделы конфигурации.

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

 RequestHeader добавляет MirrorID "зеркало 12"
RequestHeader сбросил MirrorID

Таким образом, MirrorID заголовок не устанавливается. В обратном случае для заголовка MirrorID устанавливается значение «зеркало 12».

Ранняя и поздняя обработка

mod_headers может применяться как в начале, так и в конце запроса. Обычный режим является поздним, когда заголовки запросов устанавливаются непосредственно перед запуском генератора контента, а заголовки ответов — сразу после отправки ответа по сети. Всегда используйте поздний режим на работающем сервере.

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

Поскольку ранние директивы обрабатываются до прохождения конфигурации пути запроса, ранние заголовки могут быть установлены только в контексте основного сервера или виртуального хоста. Ранние директивы не могут зависеть от пути запроса, поэтому они не будут работать в таких контекстах, как <Directory> или <Location> .

Примеры

Скопируйте все заголовки запроса, начинающиеся с «TS», в заголовки ответа:
```
 Эхо заголовка ^TS 
```
Добавьте заголовок MyHeader к ответу, включая отметку времени, когда запрос был получен и сколько времени потребовалось, чтобы начать обслуживание запроса. Этот заголовок может использоваться клиентом для интуитивного определения нагрузки на сервер или для изоляции узких мест между клиентом и сервером.
```
 Набор заголовков MyHeader "%D %t" 
```
приводит к тому, что этот заголовок добавляется к ответу:

MyHeader: D=3775428 t=991424704447256
Передай привет Джо
```
 Заголовок установил MyHeader «Привет, Джо. Apache потребовалось %D микросекунд, чтобы обработать этот запрос». 
```
приводит к тому, что этот заголовок добавляется к ответу:

MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request.
Условно отправлять MyHeader ответ тогда и только тогда, когда MyRequestHeader в запросе присутствует заголовок. Это полезно для построения заголовков в ответ на некоторые действия клиента. Обратите внимание, что для этого примера требуются услуги модуля mod_setenvif .
```
 SetEnvIf MyRequestHeader мое значение HAVE_MyRequestHeader
Набор заголовков MyHeader "%D %t mytext" env=HAVE_MyRequestHeader 
```
Если заголовок MyRequestHeader: myvalue присутствует в HTTP-запросе, ответ будет содержать следующий заголовок:

MyHeader: D=3775428 t=991424704447256 mytext
Включите DAV для работы с Apache, использующим HTTP через оборудование SSL (описание проблемы), заменив https: на http: в заголовке Destination :
```
 RequestHeader edit Destination ^https: http: Early 
```
Установите одно и то же значение заголовка при нескольких неисключительных условиях, но не дублируйте значение в конечном заголовке. Если к запросу применяются все следующие условия (т. е. если для запроса существуют все переменные CGI , NO_CACHE и среды): NO_STORE
```
 Слияние заголовков Cache-Control no-cache env=CGI
Слияние заголовков Cache-Control no-cache env=NO_CACHE
Слияние заголовков Cache-Control no-store env=NO_STORE 
```
тогда ответ будет содержать следующий заголовок:

Cache-Control: no-cache, no-store

Если append бы вместо merge , то ответ содержал бы следующий заголовок:

Cache-Control: no-cache, no-cache, no-store
Установите тестовый файл cookie тогда и только тогда, когда клиент не отправлял нам файл cookie.
```
 Набор заголовков Set-Cookie testcookie "expr=-z %{req:Cookie}" 
```
Добавьте заголовок кэширования для ответов с кодом состояния HTTP 200.
```
 Заголовок добавляет Cache-Control s-maxage=600 "expr=%{REQUEST_STATUS} == 200" 
```

Директива заголовка

Описание:	Настройка заголовков ответа HTTP
Синтаксис:	`Header [condition] add\|append\|echo\|edit\|edit*\|merge\|set\|setifempty\|unset\|note header [[expr=]value [replacement] [early\|env=[!]varname\|expr=expression]]`
Контекст:	конфигурация сервера, виртуальный хост, каталог, .htaccess
Переопределить:	Информация о файле
Положение дел:	Расширение
Модуль:	mod_headers
Совместимость:	SetIfEmpty доступно в версии 2.4.7 и выше, expr=value доступно в версии 2.4.10 и выше.

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

Необязательный аргумент условия определяет, с какими внутренними таблицами ответов будет работать эта директива. Несмотря на название, значение по умолчанию не onsuccess ограничивает действие ответами с кодом состояния 2xx. Заголовки, установленные в этом условии, все еще используются, когда, например, запрос успешно проксируется или генерируется CGI, даже если они сгенерировали код состояния сбоя.

Если ваше действие является функцией существующего заголовка, вам может потребоваться указать условие always , в зависимости от того, в какой внутренней таблице был установлен исходный заголовок. Таблица, которая соответствует, always используется для локально сгенерированных ответов об ошибках, а также успешных ответов. Также обратите внимание, что повторение этой директивы с обоими условиями имеет смысл в некоторых сценариях, потому что always это не надмножество onsuccess по отношению к существующим заголовкам:

Вы добавляете заголовок к локально сгенерированному неуспешному (не 2xx) ответу, такому как перенаправление, и в этом случае в окончательном always ответе используется только таблица, соответствующая.
Вы изменяете или удаляете заголовок, сгенерированный сценарием CGI, и в этом случае сценарии CGI находятся в таблице, соответствующей, always а не в таблице по умолчанию.
Вы изменяете или удаляете заголовок, созданный какой-либо частью сервера, но этот заголовок не найден по onsuccess условию по умолчанию.

Отдельно от параметра условия , описанного выше, вы можете ограничить действие на основе кодов состояния HTTP, например, для проксируемых или CGI-запросов. См. пример использования %{REQUEST_STATUS} в разделе выше.

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

add

Заголовок ответа добавляется к существующему набору заголовков, даже если этот заголовок уже существует. Это может привести к тому, что два (или более) заголовка будут иметь одно и то же имя. set Это может привести к непредвиденным последствиям , и вообще вместо этого следует использовать append или . merge

append

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

echo

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

edit

edit*

Если этот заголовок ответа существует, его значение преобразуется в соответствии с поиском и заменой регулярного выражения . Аргумент значения — это регулярное выражение , а замена — это строка замены, которая может содержать обратные ссылки или спецификаторы формата. Форма edit будет совпадать и заменять ровно один раз в значении заголовка, тогда как edit* форма будет заменять каждый экземпляр шаблона поиска, если он встречается более одного раза.

merge

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

set

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

setifempty

Заголовок запроса устанавливается, но только если нет предыдущего заголовка с таким именем. Заголовок Content-Type является особым вариантом использования, поскольку может быть вероятность того, что его значение было определено, но заголовок не является частью ответа при setifempty оценке. Безопаснее использовать set для этого варианта использования, как в следующем примере:

 Заголовок установил Content-Type "text/plain" "expr=-z %{CONTENT_TYPE}"

unset

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

note

Значение именованного заголовка ответа копируется во внутреннюю заметку, имя которой задается значением . Это полезно, если заголовок, отправленный CGI или прокси-ресурсом, сконфигурирован как неустановленный, но также должен быть зарегистрирован.
Доступно в версии 2.4.7 и выше.

За этим аргументом следует имя заголовка , которое может включать последнее двоеточие, но это не обязательно. Регистр игнорируется для set , append , merge , и . Имя заголовка чувствительно к регистру и может быть регулярным выражением . add unset edit echo

Для set , append , merge и в качестве следующего аргумента указывается add значение . Если значение содержит пробелы, оно должно быть заключено в двойные кавычки. value может быть строкой символов, строкой, содержащей определенные спецификаторы формата (и символьные литералы), или выражением ap_expr с префиксом expr= mod_headers

В value поддерживаются следующие спецификаторы формата :

Формат	Описание
`%%`	Знак процента
`%t`	Время получения запроса в универсальном скоординированном времени с эпохи (1 января 1970 г.), измеряемое в микросекундах. Перед значением стоит `t=` .
`%D`	Время с момента получения запроса до момента отправки заголовков по сети. Это мера продолжительности запроса. Перед значением стоит `D=` . Значение измеряется в микросекундах.
`%l`	Текущие средние значения нагрузки самого сервера. Он предназначен для отображения значений, полученных с помощью `getloadavg()` и представляет собой текущее среднее значение нагрузки, среднее значение за 5 минут и среднее значение за 15 минут. Перед значением стоит , `l=` а каждое среднее значение разделено `/` . Доступно в версии 2.4.4 и более поздних.
`%i`	Текущий процент простоя httpd (от 0 до 100) на основе доступных процессов и потоков. Перед значением стоит `i=` . Доступно в версии 2.4.4 и более поздних.
`%b`	Текущий процент занятости httpd (от 0 до 100) на основе доступных процессов и потоков. Перед значением стоит `b=` . Доступно в версии 2.4.4 и более поздних.
`%{VARNAME}e`	Содержимое переменной окружения `VARNAME` .
`%{VARNAME}s`	Содержимое переменной среды SSL `VARNAME` , если `mod_ssl` она включена.

Примечание

Спецификатор %s формата доступен только в Apache 2.1 и более поздних версиях; его можно использовать вместо того, %e чтобы избежать накладных расходов на включение SSLOptions +StdEnvVars . Если SSLOptions +StdEnvVars все равно необходимо включить по какой-то другой причине, %e это будет более эффективно, чем %s .

Примечание о значениях выражений

Когда параметр value использует синтаксический анализатор ap_expr, синтаксис некоторых выражений будет отличаться от примеров, оценивающих логические выражения, такие как <If>:

Отправной точкой грамматики является «строка», а не «выражение».
Вызовы функций используют синтаксис %{funcname:arg}, а не funcname(arg).
Функции с несколькими аргументами в настоящее время недоступны из этой начальной точки.

Укажите весь параметр, например

 Заголовок установил foo-checksum "expr=%{md5:foo}"

Ибо edit есть как аргумент значения , который является регулярным выражением , так и дополнительная строка замены . Начиная с версии 2.4.7 строка замены может также содержать спецификаторы формата.

За директивой Header может следовать дополнительный аргумент, который может быть любым из:

early

Определяет раннюю обработку.

env=[!]varname

Директива применяется тогда и только тогда, когда varname существует переменная окружения. A ! перед varname отменяет проверку, поэтому директива применяется только в том случае, если varname она не установлена.

expr=expression

Директива применяется тогда и только тогда, когда выражение оценивается как истинное. Подробная информация о синтаксисе выражения и вычислении задокументирована в документации ap_expr.

 # Это задерживает оценку предложения условия по сравнению с <If>
Заголовок всегда устанавливает мое значение CustomHeader "expr=%{REQUEST_URI} =~ m#^/special_path.php$#"

За исключением раннего режима, Header директивы обрабатываются непосредственно перед отправкой ответа в сеть. Это означает, что можно установить и/или переопределить большинство заголовков, за исключением некоторых заголовков, добавленных фильтром заголовков HTTP. До версии 2.2.12 с помощью этой директивы нельзя было изменить заголовок Content-Type.

Директива заголовка запроса

Описание:	Настройка заголовков HTTP-запроса
Синтаксис:	`RequestHeader add\|append\|edit\|edit*\|merge\|set\|setifempty\|unset header [[expr=]value [replacement] [early\|env=[!]varname\|expr=expression]]`
Контекст:	конфигурация сервера, виртуальный хост, каталог, .htaccess
Переопределить:	Информация о файле
Положение дел:	Расширение
Модуль:	mod_headers
Совместимость:	SetIfEmpty доступно в версии 2.4.7 и выше, expr=value доступно в версии 2.4.10 и выше.

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

add: Заголовок запроса добавляется к существующему набору заголовков, даже если этот заголовок уже существует. Это может привести к тому, что два (или более) заголовка будут иметь одно и то же имя. set Это может привести к непредвиденным последствиям , и вообще вместо этого следует использовать append или . merge
append: Заголовок запроса добавляется к любому существующему заголовку с тем же именем. Когда новое значение объединяется с существующим заголовком, оно отделяется от существующего заголовка запятой. Это стандартный способ HTTP для присвоения заголовку нескольких значений.
edit
edit*: Если этот заголовок запроса существует, его значение преобразуется в соответствии с поиском и заменой регулярного выражения . Аргумент значения — это регулярное выражение , а замена — это строка замены, которая может содержать обратные ссылки или спецификаторы формата. Форма edit будет совпадать и заменять ровно один раз в значении заголовка, тогда как edit* форма будет заменять каждый экземпляр шаблона поиска, если он встречается более одного раза.
merge: Заголовок запроса добавляется к любому существующему заголовку с тем же именем, если добавляемое значение уже не появляется в списке значений существующего заголовка, разделенных запятыми. Когда новое значение объединяется с существующим заголовком, оно отделяется от существующего заголовка запятой. Это стандартный способ HTTP для присвоения заголовку нескольких значений. Значения сравниваются с учетом регистра и после обработки всех спецификаторов формата. Значения в двойных кавычках считаются отличными от идентичных значений без кавычек.
set: Заголовок запроса установлен, заменяя любой предыдущий заголовок этим именем
setifempty: Заголовок запроса устанавливается, но только если нет предыдущего заголовка с таким именем.
Доступно в версии 2.4.7 и выше.
unset: Заголовок запроса с таким именем удаляется, если он существует. Если есть несколько заголовков с одинаковым именем, все они будут удалены. значение должно быть опущено.

За этим аргументом следует имя заголовка, которое может включать последнее двоеточие, но это не обязательно. Регистр игнорируется. Для set , append , merge и в качестве третьего аргумента задается add значение . Если значение содержит пробелы, оно должно быть заключено в двойные кавычки. Для не следует указывать значение . value может быть строкой символов, строкой, содержащей спецификаторы формата, или их комбинацией. Поддерживаемые спецификаторы формата такие же, как и для , подробности см. здесь. Поскольку требуются как значение , так и замена , а также регулярное выражение и строка замены соответственно. unset Header edit

За директивой RequestHeader может следовать дополнительный аргумент, который может быть любым из:

early: Определяет раннюю обработку.
env=[!]varname: Директива применяется тогда и только тогда, когда varname существует переменная окружения. A ! перед varname отменяет проверку, поэтому директива применяется только в том случае, если varname она не установлена.
expr=expression: Директива применяется тогда и только тогда, когда выражение оценивается как истинное. Подробная информация о синтаксисе выражения и вычислении задокументирована в документации ap_expr.

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