Updated mod_headers documentation to coincide with addition of RequestHeader

directive.
PR:
Obtained from:
Reviewed by:

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@89181 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/docs/manual/mod/mod_headers.html b/docs/manual/mod/mod_headers.html
index da1d7e19bc3b8107d95b066849ad1ec55bf43ecd..18d0433e822eb9d6bea03b6a0ae29d629e1cbcae 100644 (file)
--- a/docs/manual/mod/mod_headers.html
+++ b/docs/manual/mod/mod_headers.html
@@ -36,21 +36,117 @@ REL="Help"
 <A
 HREF="module-dict.html#Compatibility"
 REL="Help"
-><STRONG>Compatibility:</STRONG></A> Available in Apache 1.2 and later.
+><STRONG>Compatibility:</STRONG></A> Available in Apache 1.2 and later. In
+Apache 2.0 the Header directive was replaced with Header.
 </P>
 
 <h2>Summary</h2>
 
-This module provides a directive to control the sending of HTTP
-headers.  Headers can be merged, replaced or removed. 
+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="#header">RequestHeader</A>
 <LI><A HREF="#header">Header</A>
 </UL>
 
 <HR>
 
+<H2><A NAME="header">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>
+
+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:
+
+<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>
+
+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 &lt;Directory&gt;, &lt;Location&gt; and &lt;Files&gt;
+sections, and within .htaccess files.
+<P>
+The RequestHeader directives are processed in the following order:
+<OL>
+<LI>main server
+<LI>virtual host
+<LI>&lt;Directory&gt; sections and .htaccess
+<LI>&lt;Location&gt;
+<LI>&lt;Files&gt;
+</OL>
+
+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>
+
+<HR>
+
 <H2><A NAME="header">Header</A> directive</H2>
 <A
  HREF="directive-dict.html#Syntax"
@@ -79,9 +175,11 @@ headers.  Headers can be merged, replaced or removed.
  REL="Help"
 ><STRONG>Module:</STRONG></A> mod_header<P>
 
-This directive can replace, merge or remove HTTP response headers. The
-action it performs is determined by the first argument. This can be one
-of the following values:
+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, as with
+RequestHeader:
 
 <UL>
 <LI><STRONG>set</STRONG><BR>
@@ -112,9 +210,9 @@ For unset, no value should be given.
 
 <H3>Order of Processing</H3>
 
-The Header directive can occur almost anywhere within the server
-configuration. It is valid in the main server config and virtual host
-sections, inside &lt;Directory&gt;, &lt;Location&gt; and &lt;Files&gt;
+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 &lt;Directory&gt;, &lt;Location&gt; and &lt;Files&gt;
 sections, and within .htaccess files.
 <P>
 The Header directives are processed in the following order:
@@ -137,9 +235,8 @@ header is set to "John P. Doe".
 <P>
 
 The Header directives are processed just before the response is sent
-by its handler. These means that some headers that are added just
-before the response is sent cannot be unset or overridden. This
-includes headers such as "Date" and "Server".
+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" -->