granicus.if.org Git - apache/blob - docs/manual/mod/mod_headers.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4
   5 <!--
   6  Copyright 2002-2004 The Apache Software Foundation
   7
   8  Licensed under the Apache License, Version 2.0 (the "License");
   9  you may not use this file except in compliance with the License.
  10  You may obtain a copy of the License at
  11
  12      http://www.apache.org/licenses/LICENSE-2.0
  13
  14  Unless required by applicable law or agreed to in writing, software
  15  distributed under the License is distributed on an "AS IS" BASIS,
  16  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  See the License for the specific language governing permissions and
  18  limitations under the License.
  19 -->
  20
  21 <modulesynopsis metafile="mod_headers.xml.meta">
  22
  23 <name>mod_headers</name>
  24 <description>Customization of HTTP request and response
  25 headers</description>
  26 <status>Extension</status>
  27 <sourcefile>mod_headers.c</sourcefile>
  28 <identifier>headers_module</identifier>
  29 <compatibility><directive module="mod_headers">RequestHeader</directive>
  30 is available only in Apache 2.0</compatibility>
  31
  32 <summary>
  33     <p>This module provides directives to control and modify HTTP
  34     request and response headers. Headers can be merged, replaced
  35     or removed.</p>
  36 </summary>
  37
  38 <section id="order"><title>Order of Processing</title>
  39
  40     <p>The directives provided by <module>mod_headers</module> can
  41     occur almost anywhere within the server configuration, and can be
  42     limited in scope by enclosing them in <a
  43     href="../sections.html">configuration sections</a>.</p>
  44
  45     <p>Order of processing is important and is affected both by the
  46     order in the configuration file and by placement in <a
  47     href="../sections.html#mergin">configuration sections</a>. These
  48     two headers have a different effect if reversed:</p>
  49
  50     <example>
  51       RequestHeader append MirrorID "mirror 12"<br />
  52       RequestHeader unset MirrorID
  53     </example>
  54
  55     <p>This way round, the <code>MirrorID</code> header is not set. If
  56     reversed, the MirrorID header is set to "mirror 12".</p>
  57 </section>
  58
  59 <section id="examples"><title>Examples</title>
  60
  61     <ol>
  62       <li>
  63         Copy all request headers that begin with "TS" to the
  64         response headers:
  65
  66         <example>
  67           Header echo ^TS
  68         </example>
  69       </li>
  70
  71       <li>
  72         Add a header, <code>MyHeader</code>, to the response including a
  73         timestamp for when the request was received and how long it
  74         took to begin serving the request. This header can be used by
  75         the client to intuit load on the server or in isolating
  76         bottlenecks between the client and the server.
  77
  78         <example>
  79           Header add MyHeader "%D %t"
  80         </example>
  81
  82         <p>results in this header being added to the response:</p>
  83
  84         <example>
  85           MyHeader: D=3775428 t=991424704447256
  86         </example>
  87       </li>
  88
  89       <li>
  90         Say hello to Joe
  91
  92         <example>
  93           Header add MyHeader "Hello Joe. It took %D microseconds \<br />
  94           for Apache to serve this request."
  95         </example>
  96
  97         <p>results in this header being added to the response:</p>
  98
  99         <example>
 100           MyHeader: Hello Joe. It took D=3775428 microseconds for Apache
 101           to serve this request.
 102         </example>
 103       </li>
 104
 105       <li>
 106         Conditionally send <code>MyHeader</code> on the response if and
 107         only if header "MyRequestHeader" is present on the request. This
 108         is useful for constructing headers in response to some client
 109         stimulus. Note that this example requires the services of the
 110         <module>mod_setenvif</module> module.
 111
 112         <example>
 113           SetEnvIf MyRequestHeader value HAVE_MyRequestHeader<br />
 114           Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader<br />
 115        </example>
 116
 117        <p>If the header <code>MyRequestHeader: value</code> is present on
 118        the HTTP request, the response will contain the following header:</p>
 119
 120        <example>
 121          MyHeader: D=3775428 t=991424704447256 mytext
 122        </example>
 123       </li>
 124     </ol>
 125 </section>
 126
 127 <directivesynopsis>
 128 <name>RequestHeader</name>
 129 <description>Configure HTTP request headers</description>
 130 <syntax>RequestHeader set|append|add|unset <var>header</var>
 131 [<var>value</var>]</syntax>
 132 <contextlist><context>server config</context><context>virtual host</context>
 133 <context>directory</context><context>.htaccess</context></contextlist>
 134 <override>FileInfo</override>
 135
 136 <usage>
 137     <p>This directive can replace, merge or remove HTTP request
 138     headers. The header is modified just before the content handler
 139     is run, allowing incoming headers to be modified. The action it
 140     performs is determined by the first argument. This can be one
 141     of the following values:</p>
 142
 143     <dl>
 144     <dt><code>set</code></dt>
 145     <dd>The request header is set, replacing any previous header
 146     with this name</dd>
 147
 148     <dt><code>append</code></dt>
 149     <dd>The request header is appended to any existing header of the
 150     same name. When a new value is merged onto an existing header
 151     it is separated from the existing header with a comma. This
 152     is the HTTP standard way of giving a header multiple
 153     values.</dd>
 154
 155     <dt><code>add</code></dt>
 156     <dd>The request header is added to the existing set of headers,
 157     even if this header already exists. This can result in two
 158     (or more) headers having the same name. This can lead to
 159     unforeseen consequences, and in general <code>append</code> should be
 160     used instead.</dd>
 161
 162     <dt><code>unset</code></dt>
 163     <dd>The request header of this name is removed, if it exists. If
 164     there are multiple headers of the same name, all will be removed.</dd>
 165     </dl>
 166
 167     <p>This argument is followed by a header name, which can
 168     include the final colon, but it is not required. Case is
 169     ignored. For <code>add</code>, <code>append</code> and
 170     <code>set</code> a <var>value</var> is given as the third argument. If
 171     <var>value</var> contains spaces, it should be surrounded by double
 172     quotes. For unset, no <var>value</var> should be given.</p>
 173
 174     <p>The <directive>RequestHeader</directive> directive is processed
 175     just before the request is run by its handler in the fixup phase.
 176     This should allow headers generated by the browser, or by Apache
 177     input filters to be overridden or modified.</p>
 178 </usage>
 179 </directivesynopsis>
 180
 181 <directivesynopsis>
 182 <name>Header</name>
 183 <description>Configure HTTP response headers</description>
 184 <syntax>Header set|append|add|unset|echo  <var>header</var>
 185 [<var>value</var> [env=[!]<var>variable</var>]]</syntax>
 186 <contextlist><context>server config</context><context>virtual host</context>
 187 <context>directory</context><context>.htaccess</context></contextlist>
 188 <override>FileInfo</override>
 189
 190 <usage>
 191     <p>This directive can replace, merge or remove HTTP response
 192     headers. The header is modified just after the content handler
 193     and output filters are run, allowing outgoing headers to be
 194     modified. The action it performs is determined by the first
 195     argument. This can be one of the following values:</p>
 196
 197     <dl>
 198     <dt><code>set</code></dt>
 199     <dd>The response header is set, replacing any previous header
 200     with this name. The <var>value</var> may be a format string.</dd>
 201
 202     <dt><code>append</code></dt>
 203     <dd>The response header is appended to any existing header of
 204     the same name. When a new value is merged onto an existing
 205     header it is separated from the existing header with a comma.
 206     This is the HTTP standard way of giving a header multiple values.</dd>
 207
 208     <dt><code>add</code></dt>
 209     <dd>The response header is added to the existing set of headers,
 210     even if this header already exists. This can result in two
 211     (or more) headers having the same name. This can lead to
 212     unforeseen consequences, and in general "append" should be
 213     used instead.</dd>
 214
 215     <dt><code>unset</code></dt>
 216     <dd>The response header of this name is removed, if it exists.
 217     If there are multiple headers of the same name, all will be
 218     removed.</dd>
 219
 220     <dt><code>echo</code></dt>
 221     <dd>Request headers with this name are echoed back in the
 222     response headers. <var>header</var> may be a regular expression.</dd>
 223     </dl>
 224
 225     <p>This argument is followed by a <var>header</var> name, which
 226     can include the final colon, but it is not required. Case is
 227     ignored for <code>set</code>, <code>append</code>, <code>add</code>
 228     and <code>unset</code>. The <var>header</var> name for <code>echo</code>
 229     is case sensitive and may be a regular expression.</p>
 230
 231     <p>For <code>add</code>, <code>append</code> and <code>set</code> a
 232     <var>value</var> is specified as the third argument. If <var>value</var>
 233     contains spaces, it should be surrounded by doublequotes.
 234     <var>value</var> may be a character string, a string containing format
 235     specifiers or a combination of both. The following format specifiers
 236     are supported in <var>value</var>:</p>
 237
 238     <table border="1">
 239     <tr><td><code>%t</code></td>
 240         <td>The time the request was received in Universal Coordinated Time
 241         since the epoch (Jan. 1, 1970) measured in microseconds. The value
 242         is preceded by <code>t=</code>.</td></tr>
 243
 244     <tr><td><code>%D</code></td>
 245         <td>The time from when the request was received to the time the
 246         headers are sent on the wire. This is a measure of the duration
 247         of the request. The value is preceded by <code>D=</code>.</td></tr>
 248
 249     <tr><td><code>%{FOOBAR}e</code></td>
 250         <td>The contents of the <a href="../env.html">environment
 251         variable</a> <code>FOOBAR</code>.</td></tr>
 252
 253     <tr><td><code>%{FOOBAR}s</code></td>
 254         <td>The contents of the <a href="mod_ssl.html#envvars">SSL environment
 255         variable</a> <code>FOOBAR</code>, if <module>mod_ssl</module> is enabled.</td></tr>
 256
 257     </table>
 258
 259     <note><title>Note</title>
 260
 261       <p>The <code>%s</code> format specifier is only available in
 262       Apache 2.1 and later; it can be used instead of <code>%e</code>
 263       to avoid the overhead of enabling <code>SSLOptions
 264       +StdEnvVars</code>.  If <code>SSLOptions +StdEnvVars</code> must
 265       be enabled anyway for some other reason, <code>%e</code> will be
 266       more efficient than <code>%s</code>.</p>
 267
 268     </note>
 269
 270     <p>When the <directive>Header</directive> directive is used with the
 271     <code>add</code>, <code>append</code>, or <code>set</code>
 272     argument, a fourth argument may be used to specify conditions
 273     under which the action will be taken. If the <a
 274     href="../env.html">environment variable</a> specified in the
 275     <code>env=...</code> argument exists (or if the environment
 276     variable does not exist and <code>env=!...</code> is specified)
 277     then the action specified by the <directive>Header</directive> directive
 278     will take effect. Otherwise, the directive will have no effect
 279     on the request.</p>
 280
 281     <p>The <directive>Header</directive> directives are processed just
 282     before the response is sent to the network. These means that it is
 283     possible to set and/or override most headers, except for those headers
 284     added by the header filter.</p>
 285 </usage>
 286 </directivesynopsis>
 287
 288 </modulesynopsis>
 289