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 purposes. 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

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.
• merge - appends response header to any existing header of the same name, unless the value to be appended already appears in the header's comma-delimited list of values. When a new value is merged to an existing header it is separated from the existing header value with a comma. This is the HTTP standard way of giving a header multiple values. Values are compared in a case sensitive manner, and after all format specifiers have been processed. Values in double quotes are considered different from otherwise identical unquoted values.
  
• 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.
• edit - transforms the request header (if it exists) according to a regular expression search-and-replace. The value argument is a regular expression, and the replacement is a replacement string, which may contain backreferences.

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:

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

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.
• merge - appends response header to any existing header of the same name, unless the value to be appended already appears in the header's comma-delimited list of values. When a new value is merged to an existing header it is separated from the existing header value with a comma. This is the HTTP standard way of giving a header multiple values. Values are compared in a case sensitive manner, and after all format specifiers have been processed. Values in double quotes are considered different from otherwise identical unquoted values.
  
• 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.
• edit - transforms the request header (if it exists) according to a regular expression search-and-replace. The value argument is a regular expression, and the replacement is a replacement string, which may contain backreferences.

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.