mod_headers.html revision fd709745f1226d683c57ad9bbcdd05971d214d0c
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann BGCOLOR="#FFFFFF"
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann TEXT="#000000"
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann LINK="#0000FF"
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann VLINK="#000080"
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann ALINK="#FF0000"
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<!--#include virtual="header.html" -->
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<p>This module provides for the customization of HTTP
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannresponse headers.</p>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannHREF="module-dict.html#SourceFile"
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann><STRONG>Source File:</STRONG></A> mod_headers.c
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannHREF="module-dict.html#ModuleIdentifier"
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann><STRONG>Module Identifier:</STRONG></A> headers_module
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannHREF="module-dict.html#Compatibility"
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann><STRONG>Compatibility:</STRONG></A> Available in Apache 1.2 and later.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannRequestHeader appeared in Apache 2.0.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannThis module provides directives to control and modify HTTP
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannrequest and response headers. Headers can be merged,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannreplaced or removed.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<LI><A HREF="#requestheader">RequestHeader</A>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<H2><A NAME="requestheader">RequestHeader</A> directive</H2>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann><STRONG>Syntax:</STRONG></A> RequestHeader set|append|add
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann><STRONG>Syntax:</STRONG></A> RequestHeader unset <EM>header</EM><BR>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann><STRONG>Context:</STRONG></A> server config, virtual host, access.conf,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann .htaccess<BR>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannThis directive can replace, merge or remove HTTP request headers. The header
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannis modified just before the content handler is run, allowing incoming
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannheaders to be modified. The action it performs is determined by the first
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannargument. This can be one of the following values:
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann The request header is set, replacing any previous header with this name
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann The request header is appended to any existing header of the same
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann name. When a new value is merged onto an existing header it is
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann separated from the existing header with a comma. This is the HTTP standard
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann way of giving a header multiple values.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann The request header is added to the existing set of headers, even if
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann this header already exists. This can result in two (or more) headers
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann having the same name. This can lead to unforeseen consequences, and in
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann general "append" should be used instead.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann The request header of this name is removed, if it exists. If there are
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann multiple headers of the same name, all will be removed.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannThis argument is followed by a header name, which can include the
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannfinal colon, but it is not required. Case is ignored. For
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannadd, append and set a value is given as the third argument. If this
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannvalue contains spaces, it should be surrounded by double quotes.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannFor unset, no value should be given.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannThe RequestHeader (and Header) directives can occur almost anywhere within
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannthe server configuration. It is valid in the main server config and virtual
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannhost sections, inside <Directory>, <Location> and <Files>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannsections, and within .htaccess files.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannThe RequestHeader directives are processed in the following order:
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<LI>main server
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<LI>virtual host
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<LI><Directory> sections and .htaccess
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<LI><Location>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<LI><Files>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannOrder is important. These two headers have a different effect if reversed:
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannRequestHeader append MirrorID "mirror 12"
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannRequestHeader unset MirrorID
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannThis way round, the MirrorID header is not set. If reversed, the MirrorID
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannheader is set to "mirror 12".
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannThe RequestHeader directive is processed just before the request is run
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannby its handler in the fixup phase. This should allow headers generated by
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannthe browser, or by Apache input filters to be overridden or modified.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<H2><A NAME="header">Header</A> directive</H2>
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann><STRONG>Syntax:</STRONG></A> Header set|append|add
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <EM>header</EM> <EM>value</EM> <EM>[env=[!]environment-variable]</EM><BR>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann><STRONG>Syntax:</STRONG></A> Header unset <EM>header</EM><BR>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann><STRONG>Syntax:</STRONG></A> Header echo <EM>header</EM><BR>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann><STRONG>Context:</STRONG></A> server config, virtual host, access.conf,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann .htaccess<BR>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannThis directive can replace, merge or remove HTTP response headers. The header
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannis modified just after the content handler and output filters are run,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannallowing outgoing headers to be modified. The action it performs is determined
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannby the first argument. This can be one of the following values:
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann The response header is set, replacing any previous header with this name.
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann The response header is appended to any existing header of the same
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann name. When a new value is merged onto an existing header it is
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann separated from the existing header with a comma. This is the HTTP standard
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann way of giving a header multiple values.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann The response header is added to the existing set of headers, even if
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann this header already exists. This can result in two (or more) headers
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann having the same name. This can lead to unforeseen consequences, and in
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann general "append" should be used instead.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann The response header of this name is removed, if it exists. If there are
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann multiple headers of the same name, all will be removed.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann Request headers with this name are echoed back in the response headers.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <EM>header</EM> may be a regular expression.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannThis argument is followed by a <EM>header</EM> name, which can include the
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannfinal colon, but it is not required. Case is ignored for set, append, add
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannand unset. The <EM>header</EM> name for echo is case sensitive and may be a
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannregular expression.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannadd, append and set take a <EM>value</EM> as the third argument. If
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<EM>value</EM> contains spaces, it should be surrounded by doublequotes.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<EM>value</EM> may be a character string, a string containing format
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannspecifiers or a combination of both. The following format specifiers
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann%t: The time the request was received in Universal Coordinated Time
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann since the epoch (Jan. 1, 1970) measured in microseconds. The
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann value is preceeded by "t=".
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann%D: The time from when the request was received to the time the
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann headers are sent on the wire. This is a measure of the
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann duration of the request. The value is preceeded by "D=".
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannadd, append and set may take an optional <EM>conditional clause</EM>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannas the fourth argument. The header action (add, append, set) is
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmanndone only if the <EM>conditional clause</EM> evaluates as TRUE.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannThe Header (like the RequestHeader) directives can occur almost anywhere within
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannthe server configuration. It is valid in the main server config and virtual
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannhost sections, inside <Directory>, <Location> and <Files>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannsections, and within .htaccess files.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannThe Header directives are processed in the following order:
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<LI>main server
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<LI>virtual host
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<LI><Directory> sections and .htaccess
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann<LI><Location>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<LI><Files>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannOrder is important. These two headers have a different effect if reversed:
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannHeader append Author "John P. Doe"
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannHeader unset Author
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannThis way round, the Author header is not set. If reversed, the Author
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannheader is set to "John P. Doe".
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannThe Header directives are processed just before the response is sent
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannto the network. These means that it is possible to set and/or override
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannmost headers, except for those headers added by the header filter.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<LI>Copy all request headers that begin with "TS" to the response headers:</LI>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann Header echo ^TS*
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<LI>Add a header, MyHeader, to the response including a timestamp for when
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannthe request was received and how long it took to begin serving the
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannrequest. This header can be used by the client to intuit load on
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannthe server or in isolating bottlenecks between the client and the
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann Header add MyHeader "%D %t"
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannresults in this header being added to the response:
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann MyHeader: D=3775428 t=991424704447256
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann Header add MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request."
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannresults in this header being added to the response:
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<LI>Conditionally send MyHeader on the response if and only if header
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann"MyRequestHeader" is present on the request. This is useful for
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannconstructing headers in response to some client stimulus. Note that
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannthis example requires the services of the mod_setenvif module.</LI>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann SetEnvIf MyRequestHeader value HAVE_MyRequestHeader<BR>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannIf the header "MyRequestHeader: value" is present on the HTTP request, the response
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannwill contain the following header:
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann MyHeader: D=3775428 t=991424704447256 mytext
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<!--#include virtual="footer.html" -->