diff options
Diffstat (limited to 'docs/manual/mod/mod_headers.html')
| -rw-r--r-- | docs/manual/mod/mod_headers.html | 233 |
1 files changed, 110 insertions, 123 deletions
diff --git a/docs/manual/mod/mod_headers.html b/docs/manual/mod/mod_headers.html index 72b2ea0e55..a9983f63a3 100644 --- a/docs/manual/mod/mod_headers.html +++ b/docs/manual/mod/mod_headers.html @@ -15,7 +15,7 @@ <!--#include virtual="header.html" --> <H1 ALIGN="CENTER">Module mod_headers</H1> -<p>This module provides for the customization of HTTP +<p>This module provides for the customization of HTTP request and response headers.</p> <P><A @@ -52,6 +52,76 @@ replaced or removed. <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> @@ -82,10 +152,11 @@ replaced or removed. REL="Help" ><STRONG>Module:</STRONG></A> mod_header<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>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> @@ -108,42 +179,17 @@ argument. This can be one of the following values: multiple headers of the same name, all will be removed. </UL> -This argument is followed by a header name, which can include the +<p>This argument is followed by a header name, which can include the final colon, but it is not required. Case is ignored. For -add, append and set 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. - -<H3>Order of Processing</H3> - -The RequestHeader (and Header) directives can occur almost anywhere within -the server configuration. It is valid in the main server config and virtual -host sections, inside <Directory>, <Location> and <Files> -sections, and within .htaccess files. -<P> -The RequestHeader directives are processed in the following order: -<OL> -<LI>main server -<LI>virtual host -<LI><Directory> sections and .htaccess -<LI><Location> -<LI><Files> -</OL> +<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> -Order is important. These two headers have a different effect if reversed: -<PRE> -RequestHeader append MirrorID "mirror 12" -RequestHeader unset MirrorID -</PRE> - -This way round, the MirrorID header is not set. If reversed, the MirrorID -header is set to "mirror 12". -<P> - -The RequestHeader 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> +<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> @@ -179,10 +225,11 @@ the browser, or by Apache input filters to be overridden or modified. REL="Help" ><STRONG>Module:</STRONG></A> mod_header<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>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> @@ -210,13 +257,14 @@ by the first argument. This can be one of the following values: <EM>header</EM> may be a regular expression. </UL> -This argument is followed by a <EM>header</EM> name, which can include the +<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> -add, append and set take a <EM>value</EM> as the third argument. If -<EM>value</EM> contains spaces, it should be surrounded by doublequotes. +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>: @@ -228,83 +276,22 @@ are supported in <EM>value</EM>: headers are sent on the wire. This is a measure of the duration of the request. The value is preceeded by "D=". </PRE> -add, append and set may take an optional <EM>conditional clause</EM> -as the fourth argument. The header action (add, append, set) is -done only if the <EM>conditional clause</EM> evaluates as TRUE. -<H3>Order of Processing</H3> +<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> -The Header (like the RequestHeader) directives can occur almost anywhere within -the server configuration. It is valid in the main server config and virtual -host sections, inside <Directory>, <Location> and <Files> -sections, and within .htaccess files. -<P> -The Header directives are processed in the following order: -<OL> -<LI>main server -<LI>virtual host -<LI><Directory> sections and .htaccess -<LI><Location> -<LI><Files> -</OL> - -Order is important. These two headers have a different effect if reversed: -<PRE> -Header append Author "John P. Doe" -Header unset Author -</PRE> - -This way round, the Author header is not set. If reversed, the Author -header is set to "John P. Doe". -<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> -<HR> -<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> <!--#include virtual="footer.html" --> </BODY> </HTML> |