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

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>mod_headers - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body>
  14 <div id="page-header">
  15 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  16 <p class="apache">Apache HTTP Server Version 2.1</p>
  17 <img alt="" src="../images/feather.gif" /></div>
  18 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  19 <div id="path">
  20 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs-project/">Documentation</a> &gt; <a href="../">Version 2.1</a> &gt; <a href="./">Modules</a></div>
  21 <div id="page-content">
  22 <div id="preamble"><h1>Apache Module mod_headers</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/mod/mod_headers.html" title="English">&nbsp;en&nbsp;</a> |
  25 <a href="../ja/mod/mod_headers.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
  26 <a href="../ko/mod/mod_headers.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
  27 </div>
  28 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Customization of HTTP request and response
  29 headers</td></tr>
  30 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  31 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>headers_module</td></tr>
  32 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_headers.c</td></tr>
  33 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td><code class="directive"><a href="#requestheader">RequestHeader</a></code>
  34 is available only in Apache 2.0</td></tr></table>
  35 <h3>Summary</h3>
  36
  37     <p>This module provides directives to control and modify HTTP
  38     request and response headers. Headers can be merged, replaced
  39     or removed.</p>
  40 </div>
  41 <div id="quickview"><h3 class="directives">Directives</h3>
  42 <ul id="toc">
  43 <li><img alt="" src="../images/down.gif" /> <a href="#header">Header</a></li>
  44 <li><img alt="" src="../images/down.gif" /> <a href="#requestheader">RequestHeader</a></li>
  45 </ul>
  46 <h3>Topics</h3>
  47 <ul id="topics">
  48 <li><img alt="" src="../images/down.gif" /> <a href="#order">Order of Processing</a></li>
  49 <li><img alt="" src="../images/down.gif" /> <a href="#early">Early and Late Processing</a></li>
  50 <li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
  51 </ul></div>
  52 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  53 <div class="section">
  54 <h2><a name="order" id="order">Order of Processing</a></h2>
  55
  56     <p>The directives provided by <code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code> can
  57     occur almost anywhere within the server configuration, and can be
  58     limited in scope by enclosing them in <a href="../sections.html">configuration sections</a>.</p>
  59
  60     <p>Order of processing is important and is affected both by the
  61     order in the configuration file and by placement in <a href="../sections.html#mergin">configuration sections</a>. These
  62     two headers have a different effect if reversed:</p>
  63
  64     <div class="example"><p><code>
  65       RequestHeader append MirrorID "mirror 12"<br />
  66       RequestHeader unset MirrorID
  67     </code></p></div>
  68
  69     <p>This way round, the <code>MirrorID</code> header is not set. If
  70     reversed, the MirrorID header is set to "mirror 12".</p>
  71 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  72 <div class="section">
  73 <h2><a name="early" id="early">Early and Late Processing</a></h2>
  74     <p><code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code> can be applied either early or late
  75     in the request.  The normal mode is late, when Request Headers are
  76     set immediately before running the content generator and Response
  77     Headers just as the response is sent down the wire.  Always use
  78     Late mode in an operational server.</p>
  79
  80     <p>Early mode is designed as a test/debugging aid for developers.
  81     Directives defined using the <code>early</code> keyword are set
  82     right at the beginning of processing the request.  This means
  83     they can be used to simulate different requests and set up test
  84     cases, but it also means that headers may be changed at any time
  85     by other modules before generating a Response.</p>
  86
  87     <p>Because early directives are processed before the request path's
  88     configuration is traversed, early headers can only be set in a
  89     main server or virtual host context.  Early directives cannot depend
  90     on a request path, so they will fail in contexts such as
  91     <code>&lt;Directory&gt;</code> or <code>&lt;Location&gt;</code>.</p>
  92 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  93 <div class="section">
  94 <h2><a name="examples" id="examples">Examples</a></h2>
  95
  96     <ol>
  97       <li>
  98         Copy all request headers that begin with "TS" to the
  99         response headers:
 100
 101         <div class="example"><p><code>
 102           Header echo ^TS
 103         </code></p></div>
 104       </li>
 105
 106       <li>
 107         Add a header, <code>MyHeader</code>, to the response including a
 108         timestamp for when the request was received and how long it
 109         took to begin serving the request. This header can be used by
 110         the client to intuit load on the server or in isolating
 111         bottlenecks between the client and the server.
 112
 113         <div class="example"><p><code>
 114           Header add MyHeader "%D %t"
 115         </code></p></div>
 116
 117         <p>results in this header being added to the response:</p>
 118
 119         <div class="example"><p><code>
 120           MyHeader: D=3775428 t=991424704447256
 121         </code></p></div>
 122       </li>
 123
 124       <li>
 125         Say hello to Joe
 126
 127         <div class="example"><p><code>
 128           Header add MyHeader "Hello Joe. It took %D microseconds \<br />
 129           for Apache to serve this request."
 130         </code></p></div>
 131
 132         <p>results in this header being added to the response:</p>
 133
 134         <div class="example"><p><code>
 135           MyHeader: Hello Joe. It took D=3775428 microseconds for Apache
 136           to serve this request.
 137         </code></p></div>
 138       </li>
 139
 140       <li>
 141         Conditionally send <code>MyHeader</code> on the response if and
 142         only if header "MyRequestHeader" is present on the request. This
 143         is useful for constructing headers in response to some client
 144         stimulus. Note that this example requires the services of the
 145         <code class="module"><a href="../mod/mod_setenvif.html">mod_setenvif</a></code> module.
 146
 147         <div class="example"><p><code>
 148           SetEnvIf MyRequestHeader value HAVE_MyRequestHeader<br />
 149           Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader<br />
 150        </code></p></div>
 151
 152        <p>If the header <code>MyRequestHeader: value</code> is present on
 153        the HTTP request, the response will contain the following header:</p>
 154
 155        <div class="example"><p><code>
 156          MyHeader: D=3775428 t=991424704447256 mytext
 157        </code></p></div>
 158       </li>
 159     </ol>
 160 </div>
 161 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 162 <div class="directive-section"><h2><a name="Header" id="Header">Header</a> <a name="header" id="header">Directive</a></h2>
 163 <table class="directive">
 164 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure HTTP response headers</td></tr>
 165 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Header [<var>condition</var>] set|append|add|unset|echo
 166 <var>header</var> [<var>value</var>] [early|env=[!]<var>variable</var>]</code></td></tr>
 167 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 168 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 169 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 170 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_headers</td></tr>
 171 </table>
 172     <p>This directive can replace, merge or remove HTTP response
 173     headers. The header is modified just after the content handler
 174     and output filters are run, allowing outgoing headers to be
 175     modified.</p>
 176
 177     <p>The optional <var>condition</var> can be either <code>onsuccess</code>
 178     or <code>always</code>. It determines, which internal header table should be
 179     operated on. <code>onsuccess</code> stands for <code>2<var>xx</var></code>
 180     status codes and <code>always</code> for all status codes (including
 181     <code>2<var>xx</var></code>). Especially if you want to unset headers
 182     set by certain modules, you should try out, which table is affected.</p>
 183
 184     <p>The action it performs is determined by the second
 185     argument. This can be one of the following values:</p>
 186
 187     <dl>
 188     <dt><code>set</code></dt>
 189     <dd>The response header is set, replacing any previous header
 190     with this name. The <var>value</var> may be a format string.</dd>
 191
 192     <dt><code>append</code></dt>
 193     <dd>The response header is appended to any existing header of
 194     the same name. When a new value is merged onto an existing
 195     header it is separated from the existing header with a comma.
 196     This is the HTTP standard way of giving a header multiple values.</dd>
 197
 198     <dt><code>add</code></dt>
 199     <dd>The response header is added to the existing set of headers,
 200     even if this header already exists. This can result in two
 201     (or more) headers having the same name. This can lead to
 202     unforeseen consequences, and in general "append" should be
 203     used instead.</dd>
 204
 205     <dt><code>unset</code></dt>
 206     <dd>The response header of this name is removed, if it exists.
 207     If there are multiple headers of the same name, all will be
 208     removed. <var>value</var> must be omitted.</dd>
 209
 210     <dt><code>echo</code></dt>
 211     <dd>Request headers with this name are echoed back in the
 212     response headers. <var>header</var> may be a regular expression.
 213     <var>value</var> must be omitted.</dd>
 214     </dl>
 215
 216     <p>This argument is followed by a <var>header</var> name, which
 217     can include the final colon, but it is not required. Case is
 218     ignored for <code>set</code>, <code>append</code>, <code>add</code>
 219     and <code>unset</code>. The <var>header</var> name for <code>echo</code>
 220     is case sensitive and may be a regular expression.</p>
 221
 222     <p>For <code>add</code>, <code>append</code> and <code>set</code> a
 223     <var>value</var> is specified as the third argument. If <var>value</var>
 224     contains spaces, it should be surrounded by doublequotes.
 225     <var>value</var> may be a character string, a string containing format
 226     specifiers or a combination of both. The following format specifiers
 227     are supported in <var>value</var>:</p>
 228
 229     <table class="bordered"><tr class="header"><th>Format</th><th>Description</th></tr>
 230 <tr><td><code>%%</code></td>
 231         <td>The percent sign</td></tr>
 232 <tr class="odd"><td><code>%t</code></td>
 233         <td>The time the request was received in Universal Coordinated Time
 234         since the epoch (Jan. 1, 1970) measured in microseconds. The value
 235         is preceded by <code>t=</code>.</td></tr>
 236 <tr><td><code>%D</code></td>
 237         <td>The time from when the request was received to the time the
 238         headers are sent on the wire. This is a measure of the duration
 239         of the request. The value is preceded by <code>D=</code>.</td></tr>
 240 <tr class="odd"><td><code>%{FOOBAR}e</code></td>
 241         <td>The contents of the <a href="../env.html">environment
 242         variable</a> <code>FOOBAR</code>.</td></tr>
 243 <tr><td><code>%{FOOBAR}s</code></td>
 244         <td>The contents of the <a href="mod_ssl.html#envvars">SSL environment
 245         variable</a> <code>FOOBAR</code>, if <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is enabled.</td></tr>
 246 </table>
 247
 248     <div class="note"><h3>Note</h3>
 249       <p>The <code>%s</code> format specifier is only available in
 250       Apache 2.1 and later; it can be used instead of <code>%e</code>
 251       to avoid the overhead of enabling <code>SSLOptions
 252       +StdEnvVars</code>.  If <code>SSLOptions +StdEnvVars</code> must
 253       be enabled anyway for some other reason, <code>%e</code> will be
 254       more efficient than <code>%s</code>.</p>
 255     </div>
 256
 257     <p>The <code class="directive">Header</code> directive may be followed by an
 258     an additional argument, which may be used to specify conditions under
 259     which the action will be taken, or may be the keyword <code>early</code>
 260     to specify <a href="#early">early processing</a>. If the
 261     <a href="../env.html">environment variable</a> specified in the
 262     <code>env=<var>...</var></code> argument exists (or if the environment
 263     variable does not exist and <code>env=!<var>...</var></code> is specified)
 264     then the action specified by the <code class="directive">Header</code> directive
 265     will take effect. Otherwise, the directive will have no effect
 266     on the request.</p>
 267
 268     <p>Except in <a href="#early">early</a> mode, the
 269     <code class="directive">Header</code> directives are processed just
 270     before the response is sent to the network. These means that it is
 271     possible to set and/or override most headers, except for those headers
 272     added by the header filter.</p>
 273
 274 </div>
 275 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 276 <div class="directive-section"><h2><a name="RequestHeader" id="RequestHeader">RequestHeader</a> <a name="requestheader" id="requestheader">Directive</a></h2>
 277 <table class="directive">
 278 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure HTTP request headers</td></tr>
 279 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RequestHeader set|append|add|unset <var>header</var>
 280 [<var>value</var>] [early|env=[!]<var>variable</var>]</code></td></tr>
 281 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 282 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 283 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 284 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_headers</td></tr>
 285 </table>
 286     <p>This directive can replace, merge or remove HTTP request
 287     headers. The header is modified just before the content handler
 288     is run, allowing incoming headers to be modified. The action it
 289     performs is determined by the first argument. This can be one
 290     of the following values:</p>
 291
 292     <dl>
 293     <dt><code>set</code></dt>
 294     <dd>The request header is set, replacing any previous header
 295     with this name</dd>
 296
 297     <dt><code>append</code></dt>
 298     <dd>The request header is appended to any existing header of the
 299     same name. When a new value is merged onto an existing header
 300     it is separated from the existing header with a comma. This
 301     is the HTTP standard way of giving a header multiple
 302     values.</dd>
 303
 304     <dt><code>add</code></dt>
 305     <dd>The request header is added to the existing set of headers,
 306     even if this header already exists. This can result in two
 307     (or more) headers having the same name. This can lead to
 308     unforeseen consequences, and in general <code>append</code> should be
 309     used instead.</dd>
 310
 311     <dt><code>unset</code></dt>
 312     <dd>The request header of this name is removed, if it exists. If
 313     there are multiple headers of the same name, all will be removed.
 314     <var>value</var> must be omitted.</dd>
 315     </dl>
 316
 317     <p>This argument is followed by a header name, which can
 318     include the final colon, but it is not required. Case is
 319     ignored. For <code>add</code>, <code>append</code> and
 320     <code>set</code> a <var>value</var> is given as the third argument. If
 321     <var>value</var> contains spaces, it should be surrounded by double
 322     quotes. For unset, no <var>value</var> should be given.
 323     <var>value</var> may be a character string, a string containing format
 324     specifiers or a combination of both. The supported format specifiers
 325     are the same as for the <code class="directive"><a href="#header">Header</a></code>,
 326     please have a look there for details.</p>
 327
 328     <p>The <code class="directive">RequestHeader</code> directive may be followed by
 329     an additional argument, which may be used to specify conditions under
 330     which the action will be taken, or may be the keyword <code>early</code>
 331     to specify <a href="#early">early processing</a>. If the
 332     <a href="../env.html">environment
 333     variable</a> specified in the <code>env=<var>...</var></code> argument
 334     exists (or if the environment variable does not exist and
 335     <code>env=!<var>...</var></code> is specified) then the action specified
 336     by the <code class="directive">RequestHeader</code> directive will take effect.
 337     Otherwise, the directive will have no effect on the request.</p>
 338
 339     <p>Except in <a href="#early">early</a> mode, the
 340     <code class="directive">RequestHeader</code> directive is processed
 341     just before the request is run by its handler in the fixup phase.
 342     This should allow headers generated by the browser, or by Apache
 343     input filters to be overridden or modified.</p>
 344
 345 </div>
 346 </div>
 347 <div class="bottomlang">
 348 <p><span>Available Languages: </span><a href="../en/mod/mod_headers.html" title="English">&nbsp;en&nbsp;</a> |
 349 <a href="../ja/mod/mod_headers.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
 350 <a href="../ko/mod/mod_headers.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
 351 </div><div id="footer">
 352 <p class="apache">Copyright 1999-2004 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 353 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
 354 </body></html>