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

Quick start

Sample .htaccess configuration to add cache-control headers

<Files *.php>
  # setup Cache-Control to public and max-age
  Header set Cache-Control public,max-age=3600
</Files>
<Files *.xml>
  # disable all caching via Cache-Control header
  Header set Cache-Control "no-cache, no-store, must-revalidate, max-age=0"
</Files>

Sample httpd.conf configuration to add additional info into Server header

Header append Server "Powered by Helicon Ape"

Related articles and topics

Directives

Name Context Description
Header S V D .h configures HTTP response headers
RequestHeader S V D .h configures HTTP request headers

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.

Syntax

Header [condition] set|append|merge|add|unset|echo|edit header [value] [early|env=[!]variable]

Description

  • 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 :

    • %% — 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

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.

Syntax

RequestHeader set|append|merge|add|unset|edit header [value] [early|env=[!]variable]

Description

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

Example

# remove Referer header
RequestHeader unset Referer