mod_headers

mod_headers overview

mod_headers module enables HTTP request and response headers modification (i.e. merging, replacement or removal).

Early and Late Headers Processing

mod_headers can be applied to the request on early or late stage.

Default mode is late - Request Headers are set right before running the content generator and sending the response. Late mode must always be used on live server.

Early mode was designed for testing puposes. Directives marked with early keyword are set right at the beginning of request processing. Early headers can only be used in server and virtual host context, but are senseless in contexts like <Directory> or <Location>.

mod_headers directives

Header

Description: Configure HTTP response headers
Syntax: Header [condition] set|append|add|unset|echo header [value] [early|env=[!]variable]
Context: server config, virtual host, directory, .htaccess
Module: mod_headers

Header directive allows to replace, merge or remove HTTP response headers. The header is modified just after the content handler and output filters are run, allowing modification of outgoing headers.

The optional condition can be either onsuccess or always. It determines, which internal header table should be operated on. onsuccess stands for 2xx status codes and always for all status codes (including 2xx). Especially if you want to unset headers set by certain modules, you should try out, which table is affected.

The second argument specifies what action is performed:

  • set - sets response header and replaces any existing header with the same name. The value may be a format string.
  • append - appends response header to any existing header with the same name. When a new value is merged to an existing header it is separated from the existing header with comma.
  • add - adds response header to the existing set of headers even if such header already exists. This may result in multiple headers of the same name and lead to unpredictable consequences.
  • unset - removes response header with such name if it exists. If there are multiple headers of the same name, all will be removed. value should be omitted.
  • echo - echoes request headers in response. header may be a regular expression. value should be omitted.

The next argument is header name, which may include the final colon, but it is not required. Set, append, add and unset are case-insensitive; echo is case sensitive.

The third argument for add, append and set is value. If value contains spaces, it should be put into double quotes. value may be a character string, a string containing format specifiers or a combination of both. The following format specifiers are supported for value:

Format Description
%% Percent sign
%t The time (Universal Coordinated Time) when the request was received given in microseconds since January 1, 1970. The value is preceded by t=
%D The time from the moment the request was received till the time the headers are sent into the nete. This is a measure of request duration. The value is preceded by D=
%{FOOBAR}e The contents of the environment variable FOOBAR

Header directive may include an additional argument which may specify conditions for action to occur. It may also be early keyword to initiate early processing. If the environment variable specified in the env=... argument exists (or doesn't exist in env=!...), the action specified in Header directive will take place. Otherwise, the directive will have no effect on the request.

If not in early mode, Header directives are processed right before the response is sent to the network.

Example:

Header add MyHeader "%D %t"

will result in addition of the following header to the response:

MyHeader: D=3775428 t=991424704447256

RequestHeader

Description: Configure HTTP request headers
Syntax: RequestHeader set|append|add|unset header [value] [early|env=[!]variable]
Context: server config, virtual host, directory, .htaccess
Module: mod_headers

RequestHeader directive allows to replace, merge or remove HTTP request headers. The header is modified just before the content handler is run, allowing incoming headers to be modified. The action it performs is determined by the first argument. This can be one of the following values:

The first argument specifies what action is performed:

  • set - sets response header and replaces any existing header with the same name. The value may be a format string.
  • append - appends request header to any existing header with the same name. When a new value is merged to an existing header it is separated from the existing header with comma.
  • add - adds request header to the existing set of headers even if such header already exists. This may result in multiple headers of the same name and lead to unpredictable consequences.
  • unset - removes request header with such name if it exists. If there are multiple headers of the same name, all will be removed. value should be omitted.

The next argument is header name, which may include the final colon, but it is not required. Set, append, add and unset are case-insensitive.

The value for add, append and set is specified in the third argument, for unset no value is needed. If value contains spaces, it should be put into double quotes. value may be a character string, a string containing format specifiers or a combination of both. Format specifiers are the same as for the Header directive.

RequestHeader directive may include an additional argument which may specify conditions for action to occur. It may also be early keyword to initiate early processing. If the environment variable specified in the env=... argument exists (or doesn't exist in env=!...), the action specified in RequestHeader directive will take place. Otherwise, the directive will have no effect on the request.

If not in early mode, Header directives are processed right before the response is sent to the network.