mirror of
https://github.com/apache/httpd.git
synced 2025-05-31 12:21:16 +03:00
2feece5618
little. PR: Obtained from: Submitted by: Reviewed by: git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@89387 13f79535-47bb-0310-9956-ffa450edef68
298 lines
9.7 KiB
HTML
298 lines
9.7 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>Apache module mod_headers</TITLE>
|
|
</HEAD>
|
|
|
|
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
|
|
<BODY
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#000080"
|
|
ALINK="#FF0000"
|
|
>
|
|
<!--#include virtual="header.html" -->
|
|
<H1 ALIGN="CENTER">Module mod_headers</H1>
|
|
|
|
<p>This module provides for the customization of HTTP request and
|
|
response headers.</p>
|
|
|
|
<P><A
|
|
HREF="module-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Extension
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#SourceFile"
|
|
REL="Help"
|
|
><STRONG>Source File:</STRONG></A> mod_headers.c
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#ModuleIdentifier"
|
|
REL="Help"
|
|
><STRONG>Module Identifier:</STRONG></A> headers_module
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#Compatibility"
|
|
REL="Help"
|
|
><STRONG>Compatibility:</STRONG></A> Available in Apache 1.2 and later.
|
|
RequestHeader appeared in Apache 2.0.
|
|
</P>
|
|
|
|
<h2>Summary</h2>
|
|
|
|
This module provides directives to control and modify HTTP
|
|
request and response headers. Headers can be merged,
|
|
replaced or removed.
|
|
|
|
<H2>Directives</H2>
|
|
<UL>
|
|
<LI><A HREF="#requestheader">RequestHeader</A>
|
|
<LI><A HREF="#header">Header</A>
|
|
</UL>
|
|
|
|
<H2>Order of Processing</H2>
|
|
|
|
<p>The directives provided by mod_header can occur almost anywhere within
|
|
the server configuration. They are valid in the main server config and virtual
|
|
host sections, inside <Directory>, <Location> and <Files>
|
|
sections, and within .htaccess files.</p>
|
|
|
|
<P>The directives are processed in the following order:
|
|
<OL>
|
|
<LI>main server
|
|
<LI>virtual host
|
|
<LI><Directory> sections and .htaccess
|
|
<LI><Location>
|
|
<LI><Files>
|
|
</OL>
|
|
|
|
<p>Order is important. These two headers have a different effect if
|
|
reversed:</p>
|
|
|
|
<blockquote><code>
|
|
RequestHeader append MirrorID "mirror 12"<br>
|
|
RequestHeader unset MirrorID
|
|
</code></blockquote>
|
|
|
|
<p>This way round, the MirrorID header is not set. If reversed, the
|
|
MirrorID header is set to "mirror 12".</P>
|
|
|
|
<H2>Examples</H2>
|
|
<OL>
|
|
<LI>Copy all request headers that begin with "TS" to the response headers:</LI>
|
|
<PRE>
|
|
Header echo ^TS*
|
|
</PRE>
|
|
|
|
<LI>Add a header, MyHeader, to the response including a timestamp for when
|
|
the request was received and how long it took to begin serving the
|
|
request. This header can be used by the client to intuit load on
|
|
the server or in isolating bottlenecks between the client and the
|
|
server.</LI>
|
|
<PRE>
|
|
Header add MyHeader "%D %t"
|
|
</PRE>
|
|
results in this header being added to the response:
|
|
<PRE>
|
|
MyHeader: D=3775428 t=991424704447256
|
|
</PRE>
|
|
<LI>Say hello to Joe</LI>
|
|
<PRE>
|
|
Header add MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request."
|
|
</PRE>
|
|
results in this header being added to the response:
|
|
<PRE>
|
|
MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request.
|
|
</PRE>
|
|
|
|
<LI>Conditionally send MyHeader on the response if and only if header
|
|
"MyRequestHeader" is present on the request. This is useful for
|
|
constructing headers in response to some client stimulus. Note that
|
|
this example requires the services of the mod_setenvif module.</LI>
|
|
<PRE>
|
|
SetEnvIf MyRequestHeader value HAVE_MyRequestHeader<BR>
|
|
Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader
|
|
</PRE>
|
|
If the header "MyRequestHeader: value" is present on the HTTP request, the response
|
|
will contain the following header:
|
|
<PRE>
|
|
MyHeader: D=3775428 t=991424704447256 mytext
|
|
</PRE>
|
|
</OL>
|
|
|
|
<HR>
|
|
|
|
<H2><A NAME="requestheader">RequestHeader</A> directive</H2>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> RequestHeader set|append|add
|
|
<EM>header</EM> <EM>value</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> RequestHeader unset <EM>header</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config, virtual host, access.conf,
|
|
.htaccess<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> FileInfo<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Extension<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_header<P>
|
|
|
|
<p>This directive can 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:</p>
|
|
|
|
<UL>
|
|
<LI><STRONG>set</STRONG><BR>
|
|
The request header is set, replacing any previous header with this name
|
|
|
|
<LI><STRONG>append</STRONG><BR>
|
|
The request header is appended to any existing header of the same
|
|
name. When a new value is merged onto an existing header it is
|
|
separated from the existing header with a comma. This is the HTTP standard
|
|
way of giving a header multiple values.
|
|
|
|
<LI><STRONG>add</STRONG><BR>
|
|
The request header is added to the existing set of headers, even if
|
|
this header already exists. This can result in two (or more) headers
|
|
having the same name. This can lead to unforeseen consequences, and in
|
|
general "append" should be used instead.
|
|
|
|
<LI><STRONG>unset</STRONG><BR>
|
|
The request header of this name is removed, if it exists. If there are
|
|
multiple headers of the same name, all will be removed.
|
|
</UL>
|
|
|
|
<p>This argument is followed by a header name, which can include the
|
|
final colon, but it is not required. Case is ignored. For
|
|
<code>add</code>, <code>append</code> and <code>set</code> a value is
|
|
given as the third argument. If this value contains spaces, it should
|
|
be surrounded by double quotes. For unset, no value should be
|
|
given.</p>
|
|
|
|
<p>The <code>RequestHeader</code> directive is processed just before
|
|
the request is run by its handler in the fixup phase. This should
|
|
allow headers generated by the browser, or by Apache input filters to
|
|
be overridden or modified.</p>
|
|
|
|
<HR>
|
|
|
|
<H2><A NAME="header">Header</A> directive</H2>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> Header set|append|add
|
|
<EM>header</EM> <EM>value</EM> <EM>[env=[!]environment-variable]</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> Header unset <EM>header</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> Header echo <EM>header</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config, virtual host, access.conf,
|
|
.htaccess<BR>
|
|
<A
|
|
HREF="directive-dict.html#Override"
|
|
REL="Help"
|
|
><STRONG>Override:</STRONG></A> FileInfo<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Extension<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_header<P>
|
|
|
|
<p>This directive can replace, merge or remove HTTP response
|
|
headers. The header is modified just after the content handler and
|
|
output filters are run, allowing outgoing headers to be modified. The
|
|
action it performs is determined by the first argument. This can be
|
|
one of the following values:</p>
|
|
|
|
<UL>
|
|
<LI><STRONG>set</STRONG><BR>
|
|
The response header is set, replacing any previous header with this name.
|
|
The <EM>value</EM> may be a format string.
|
|
|
|
<LI><STRONG>append</STRONG><BR>
|
|
The response header is appended to any existing header of the same
|
|
name. When a new value is merged onto an existing header it is
|
|
separated from the existing header with a comma. This is the HTTP standard
|
|
way of giving a header multiple values.
|
|
|
|
<LI><STRONG>add</STRONG><BR>
|
|
The response header is added to the existing set of headers, even if
|
|
this header already exists. This can result in two (or more) headers
|
|
having the same name. This can lead to unforeseen consequences, and in
|
|
general "append" should be used instead.
|
|
|
|
<LI><STRONG>unset</STRONG><BR>
|
|
The response header of this name is removed, if it exists. If there are
|
|
multiple headers of the same name, all will be removed.
|
|
|
|
<LI><STRONG>echo</STRONG><BR>
|
|
Request headers with this name are echoed back in the response headers.
|
|
<EM>header</EM> may be a regular expression.
|
|
</UL>
|
|
|
|
<p>This argument is followed by a <EM>header</EM> name, which can include the
|
|
final colon, but it is not required. Case is ignored for set, append, add
|
|
and unset. The <EM>header</EM> name for echo is case sensitive and may be a
|
|
regular expression.</p>
|
|
|
|
<P>For <code>add</code>, <code>append</code> and <code>set</code> a
|
|
<EM>value</EM> is specified as the third argument. If <EM>value</EM>
|
|
contains spaces, it should be surrounded by doublequotes.
|
|
<EM>value</EM> may be a character string, a string containing format
|
|
specifiers or a combination of both. The following format specifiers
|
|
are supported in <EM>value</EM>:
|
|
<PRE>
|
|
%t: The time the request was received in Universal Coordinated Time
|
|
since the epoch (Jan. 1, 1970) measured in microseconds. The
|
|
value is preceeded by "t=".
|
|
%D: The time from when the request was received to the time the
|
|
headers are sent on the wire. This is a measure of the
|
|
duration of the request. The value is preceeded by "D=".
|
|
</PRE>
|
|
|
|
<p>When the <code>Header</code> directive is used with the
|
|
<code>add</code>, <code>append</code>, or <code>set</code> argument, a
|
|
fourth argument may be used to specify conditions under which the
|
|
action will be taken. If the <a href="../env.html">environment
|
|
variable</a> specified in the <code>env=...</code> argument exists (or
|
|
if the environment variable does not exist and <code>env=!...</code>
|
|
is specified) then the action specified by the <code>Header</code>
|
|
directive will take effect. Otherwise, the directive will have no
|
|
effect on the request.</p>
|
|
|
|
<p>The Header directives are processed just before the response is
|
|
sent to the network. These means that it is possible to set and/or
|
|
override most headers, except for those headers added by the header
|
|
filter.</p>
|
|
|
|
<!--#include virtual="footer.html" -->
|
|
</BODY>
|
|
</HTML>
|