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
 213     <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>.
 214     <var>value</var> must be omitted.</dd>
 215     </dl>
 216
 217     <p>This argument is followed by a <var>header</var> name, which
 218     can include the final colon, but it is not required. Case is
 219     ignored for <code>set</code>, <code>append</code>, <code>add</code>
 220     and <code>unset</code>. The <var>header</var> name for <code>echo</code>
 221     is case sensitive and may be a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular
 222     expression</a>.</p>
 223
 224     <p>For <code>add</code>, <code>append</code> and <code>set</code> a
 225     <var>value</var> is specified as the third argument. If <var>value</var>
 226     contains spaces, it should be surrounded by doublequotes.
 227     <var>value</var> may be a character string, a string containing format
 228     specifiers or a combination of both. The following format specifiers
 229     are supported in <var>value</var>:</p>
 230
 231     <table class="bordered"><tr class="header"><th>Format</th><th>Description</th></tr>
 232 <tr><td><code>%%</code></td>
 233         <td>The percent sign</td></tr>
 234 <tr class="odd"><td><code>%t</code></td>
 235         <td>The time the request was received in Universal Coordinated Time
 236         since the epoch (Jan. 1, 1970) measured in microseconds. The value
 237         is preceded by <code>t=</code>.</td></tr>
 238 <tr><td><code>%D</code></td>
 239         <td>The time from when the request was received to the time the
 240         headers are sent on the wire. This is a measure of the duration
 241         of the request. The value is preceded by <code>D=</code>.</td></tr>
 242 <tr class="odd"><td><code>%{FOOBAR}e</code></td>
 243         <td>The contents of the <a href="../env.html">environment
 244         variable</a> <code>FOOBAR</code>.</td></tr>
 245 <tr><td><code>%{FOOBAR}s</code></td>
 246         <td>The contents of the <a href="mod_ssl.html#envvars">SSL environment
 247         variable</a> <code>FOOBAR</code>, if <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is enabled.</td></tr>
 248 </table>
 249
 250     <div class="note"><h3>Note</h3>
 251       <p>The <code>%s</code> format specifier is only available in
 252       Apache 2.1 and later; it can be used instead of <code>%e</code>
 253       to avoid the overhead of enabling <code>SSLOptions
 254       +StdEnvVars</code>.  If <code>SSLOptions +StdEnvVars</code> must
 255       be enabled anyway for some other reason, <code>%e</code> will be
 256       more efficient than <code>%s</code>.</p>
 257     </div>
 258
 259     <p>The <code class="directive">Header</code> directive may be followed by an
 260     an additional argument, which may be used to specify conditions under
 261     which the action will be taken, or may be the keyword <code>early</code>
 262     to specify <a href="#early">early processing</a>. If the
 263     <a href="../env.html">environment variable</a> specified in the
 264     <code>env=<var>...</var></code> argument exists (or if the environment
 265     variable does not exist and <code>env=!<var>...</var></code> is specified)
 266     then the action specified by the <code class="directive">Header</code> directive
 267     will take effect. Otherwise, the directive will have no effect
 268     on the request.</p>
 269
 270     <p>Except in <a href="#early">early</a> mode, the
 271     <code class="directive">Header</code> directives are processed just
 272     before the response is sent to the network. These means that it is
 273     possible to set and/or override most headers, except for those headers
 274     added by the header filter.</p>
 275
 276 </div>
 277 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 278 <div class="directive-section"><h2><a name="RequestHeader" id="RequestHeader">RequestHeader</a> <a name="requestheader" id="requestheader">Directive</a></h2>
 279 <table class="directive">
 280 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure HTTP request headers</td></tr>
 281 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RequestHeader set|append|add|unset <var>header</var>
 282 [<var>value</var>] [early|env=[!]<var>variable</var>]</code></td></tr>
 283 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 284 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 285 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 286 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_headers</td></tr>
 287 </table>
 288     <p>This directive can replace, merge or remove HTTP request
 289     headers. The header is modified just before the content handler
 290     is run, allowing incoming headers to be modified. The action it
 291     performs is determined by the first argument. This can be one
 292     of the following values:</p>
 293
 294     <dl>
 295     <dt><code>set</code></dt>
 296     <dd>The request header is set, replacing any previous header
 297     with this name</dd>
 298
 299     <dt><code>append</code></dt>
 300     <dd>The request header is appended to any existing header of the
 301     same name. When a new value is merged onto an existing header
 302     it is separated from the existing header with a comma. This
 303     is the HTTP standard way of giving a header multiple
 304     values.</dd>
 305
 306     <dt><code>add</code></dt>
 307     <dd>The request header is added to the existing set of headers,
 308     even if this header already exists. This can result in two
 309     (or more) headers having the same name. This can lead to
 310     unforeseen consequences, and in general <code>append</code> should be
 311     used instead.</dd>
 312
 313     <dt><code>unset</code></dt>
 314     <dd>The request header of this name is removed, if it exists. If
 315     there are multiple headers of the same name, all will be removed.
 316     <var>value</var> must be omitted.</dd>
 317     </dl>
 318
 319     <p>This argument is followed by a header name, which can
 320     include the final colon, but it is not required. Case is
 321     ignored. For <code>add</code>, <code>append</code> and
 322     <code>set</code> a <var>value</var> is given as the third argument. If
 323     <var>value</var> contains spaces, it should be surrounded by double
 324     quotes. For unset, no <var>value</var> should be given.
 325     <var>value</var> may be a character string, a string containing format
 326     specifiers or a combination of both. The supported format specifiers
 327     are the same as for the <code class="directive"><a href="#header">Header</a></code>,
 328     please have a look there for details.</p>
 329
 330     <p>The <code class="directive">RequestHeader</code> directive may be followed by
 331     an additional argument, which may be used to specify conditions under
 332     which the action will be taken, or may be the keyword <code>early</code>
 333     to specify <a href="#early">early processing</a>. If the
 334     <a href="../env.html">environment
 335     variable</a> specified in the <code>env=<var>...</var></code> argument
 336     exists (or if the environment variable does not exist and
 337     <code>env=!<var>...</var></code> is specified) then the action specified
 338     by the <code class="directive">RequestHeader</code> directive will take effect.
 339     Otherwise, the directive will have no effect on the request.</p>
 340
 341     <p>Except in <a href="#early">early</a> mode, the
 342     <code class="directive">RequestHeader</code> directive is processed
 343     just before the request is run by its handler in the fixup phase.
 344     This should allow headers generated by the browser, or by Apache
 345     input filters to be overridden or modified.</p>
 346
 347 </div>
 348 </div>
 349 <div class="bottomlang">
 350 <p><span>Available Languages: </span><a href="../en/mod/mod_headers.html" title="English">&nbsp;en&nbsp;</a> |
 351 <a href="../ja/mod/mod_headers.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
 352 <a href="../ko/mod/mod_headers.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
 353 </div><div id="footer">
 354 <p class="apache">Copyright 1995-2005 The Apache Software Foundation or its licensors, as applicable.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 355 <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>
 356 </body></html>