rubbos/app/apache2/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.0</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/">Documentation</a> &gt; <a href="../">Version 2.0</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="../ko/mod/mod_headers.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
  26 </div>
  27 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Customization of HTTP request and response
  28 headers</td></tr>
  29 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  30 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>headers_module</td></tr>
  31 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_headers.c</td></tr></table>
  32 <h3>Summary</h3>
  33
  34     <p>This module provides directives to control and modify HTTP
  35     request and response headers. Headers can be merged, replaced
  36     or removed.</p>
  37 </div>
  38 <div id="quickview"><h3 class="directives">Directives</h3>
  39 <ul id="toc">
  40 <li><img alt="" src="../images/down.gif" /> <a href="#header">Header</a></li>
  41 <li><img alt="" src="../images/down.gif" /> <a href="#requestheader">RequestHeader</a></li>
  42 </ul>
  43 <h3>Topics</h3>
  44 <ul id="topics">
  45 <li><img alt="" src="../images/down.gif" /> <a href="#order">Order of Processing</a></li>
  46 <li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
  47 </ul></div>
  48 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  49 <div class="section">
  50 <h2><a name="order" id="order">Order of Processing</a></h2>
  51
  52     <p>The directives provided by <code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code> can occur
  53     almost anywhere within the server configuration. They are valid in the
  54     main server config and virtual host sections, inside
  55     <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code>,
  56     <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code> and
  57     <code class="directive"><a href="../mod/core.html#files">&lt;Files&gt;</a></code> sections,
  58     and within <code>.htaccess</code> files.</p>
  59
  60     <p>The directives are processed in the following order:</p>
  61
  62     <ol>
  63       <li>main server</li>
  64       <li>virtual host</li>
  65       <li><code class="directive">&lt;Directory&gt;</code> sections and
  66       <code>.htaccess</code></li>
  67       <li><code class="directive">&lt;Files&gt;</code></li>
  68       <li><code class="directive">&lt;Location&gt;</code></li>
  69     </ol>
  70
  71     <p>Order is important. These two headers have a different
  72     effect if reversed:</p>
  73
  74     <div class="example"><p><code>
  75       RequestHeader append MirrorID "mirror 12"<br />
  76       RequestHeader unset MirrorID
  77     </code></p></div>
  78
  79     <p>This way round, the <code>MirrorID</code> header is not set. If
  80     reversed, the MirrorID header is set to "mirror 12".</p>
  81 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  82 <div class="section">
  83 <h2><a name="examples" id="examples">Examples</a></h2>
  84
  85     <ol>
  86       <li>
  87         Copy all request headers that begin with "TS" to the
  88         response headers:
  89
  90         <div class="example"><p><code>
  91           Header echo ^TS
  92         </code></p></div>
  93       </li>
  94
  95       <li>
  96         Add a header, <code>MyHeader</code>, to the response including a
  97         timestamp for when the request was received and how long it
  98         took to begin serving the request. This header can be used by
  99         the client to intuit load on the server or in isolating
 100         bottlenecks between the client and the server.
 101
 102         <div class="example"><p><code>
 103           Header add MyHeader "%D %t"
 104         </code></p></div>
 105
 106         <p>results in this header being added to the response:</p>
 107
 108         <div class="example"><p><code>
 109           MyHeader: D=3775428 t=991424704447256
 110         </code></p></div>
 111       </li>
 112
 113       <li>
 114         Say hello to Joe
 115
 116         <div class="example"><p><code>
 117           Header add MyHeader "Hello Joe. It took %D microseconds \<br />
 118           for Apache to serve this request."
 119         </code></p></div>
 120
 121         <p>results in this header being added to the response:</p>
 122
 123         <div class="example"><p><code>
 124           MyHeader: Hello Joe. It took D=3775428 microseconds for Apache
 125           to serve this request.
 126         </code></p></div>
 127       </li>
 128
 129       <li>
 130         Conditionally send <code>MyHeader</code> on the response if and
 131         only if header "MyRequestHeader" is present on the request. This
 132         is useful for constructing headers in response to some client
 133         stimulus. Note that this example requires the services of the
 134         <code class="module"><a href="../mod/mod_setenvif.html">mod_setenvif</a></code> module.
 135
 136         <div class="example"><p><code>
 137           SetEnvIf MyRequestHeader value HAVE_MyRequestHeader<br />
 138           Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader<br />
 139        </code></p></div>
 140
 141        <p>If the header <code>MyRequestHeader: value</code> is present on
 142        the HTTP request, the response will contain the following header:</p>
 143
 144        <div class="example"><p><code>
 145          MyHeader: D=3775428 t=991424704447256 mytext
 146        </code></p></div>
 147       </li>
 148     </ol>
 149 </div>
 150 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 151 <div class="directive-section"><h2><a name="Header" id="Header">Header</a> <a name="header" id="header">Directive</a></h2>
 152 <table class="directive">
 153 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure HTTP response headers</td></tr>
 154 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Header [<var>condition</var>] set|append|add|unset|echo
 155 <var>header</var> [<var>value</var>] [env=[!]<var>variable</var>]</code></td></tr>
 156 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 157 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 158 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 159 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_headers</td></tr>
 160 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td><var>Condition</var> is available in version 2.0.51 and
 161 later</td></tr>
 162 </table>
 163     <p>This directive can replace, merge or remove HTTP response
 164     headers. The header is modified just after the content handler
 165     and output filters are run, allowing outgoing headers to be
 166     modified.</p>
 167
 168     <p>The optional <var>condition</var> can be either <code>onsuccess</code>
 169     or <code>always</code>. It determines, which internal header table should be
 170     operated on. <code>onsuccess</code> stands for <code>2<var>xx</var></code>
 171     status codes and <code>always</code> for all status codes (including
 172     <code>2<var>xx</var></code>). Especially if you want to unset headers
 173     set by certain modules, you should try out, which table is affected.</p>
 174
 175     <p>The action it performs is determined by the second
 176     argument. This can be one of the following values:</p>
 177
 178     <dl>
 179     <dt><code>set</code></dt>
 180     <dd>The response header is set, replacing any previous header
 181     with this name. The <var>value</var> may be a format string.</dd>
 182
 183     <dt><code>append</code></dt>
 184     <dd>The response header is appended to any existing header of
 185     the same name. When a new value is merged onto an existing
 186     header it is separated from the existing header with a comma.
 187     This is the HTTP standard way of giving a header multiple values.</dd>
 188
 189     <dt><code>add</code></dt>
 190     <dd>The response header is added to the existing set of headers,
 191     even if this header already exists. This can result in two
 192     (or more) headers having the same name. This can lead to
 193     unforeseen consequences, and in general "append" should be
 194     used instead.</dd>
 195
 196     <dt><code>unset</code></dt>
 197     <dd>The response header of this name is removed, if it exists.
 198     If there are multiple headers of the same name, all will be
 199     removed.</dd>
 200
 201     <dt><code>echo</code></dt>
 202     <dd>Request headers with this name are echoed back in the
 203     response headers. <var>header</var> may be a regular expression.</dd>
 204     </dl>
 205
 206     <p>This argument is followed by a <var>header</var> name, which
 207     can include the final colon, but it is not required. Case is
 208     ignored for <code>set</code>, <code>append</code>, <code>add</code>
 209     and <code>unset</code>. The <var>header</var> name for <code>echo</code>
 210     is case sensitive and may be a regular expression.</p>
 211
 212     <p>For <code>add</code>, <code>append</code> and <code>set</code> a
 213     <var>value</var> is specified as the third argument. If <var>value</var>
 214     contains spaces, it should be surrounded by doublequotes.
 215     <var>value</var> may be a character string, a string containing format
 216     specifiers or a combination of both. The following format specifiers
 217     are supported in <var>value</var>:</p>
 218
 219     <table class="bordered">
 220
 221     <tr><td><code>%t</code></td>
 222         <td>The time the request was received in Universal Coordinated Time
 223         since the epoch (Jan. 1, 1970) measured in microseconds. The value
 224         is preceded by <code>t=</code>.</td></tr>
 225
 226     <tr><td><code>%D</code></td>
 227         <td>The time from when the request was received to the time the
 228         headers are sent on the wire. This is a measure of the duration
 229         of the request. The value is preceded by <code>D=</code>.</td></tr>
 230
 231     <tr><td><code>%{FOOBAR}e</code></td>
 232         <td>The contents of the <a href="../env.html">environment
 233         variable</a> <code>FOOBAR</code>.</td></tr>
 234     </table>
 235
 236     <p>When the <code class="directive">Header</code> directive is used with the
 237     <code>add</code>, <code>append</code>, or <code>set</code>
 238     argument, a fourth argument may be used to specify conditions
 239     under which the action will be taken. If the <a href="../env.html">environment variable</a> specified in the
 240     <code>env=...</code> argument exists (or if the environment
 241     variable does not exist and <code>env=!...</code> is specified)
 242     then the action specified by the <code class="directive">Header</code> directive
 243     will take effect. Otherwise, the directive will have no effect
 244     on the request.</p>
 245
 246     <p>The <code class="directive">Header</code> directives are processed just
 247     before the response is sent to the network. These means that it is
 248     possible to set and/or override most headers, except for those headers
 249     added by the header filter.</p>
 250
 251 </div>
 252 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 253 <div class="directive-section"><h2><a name="RequestHeader" id="RequestHeader">RequestHeader</a> <a name="requestheader" id="requestheader">Directive</a></h2>
 254 <table class="directive">
 255 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure HTTP request headers</td></tr>
 256 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RequestHeader set|append|add|unset <var>header</var>
 257 [<var>value</var> [env=[!]<var>variable</var>]]</code></td></tr>
 258 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 259 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 260 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 261 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_headers</td></tr>
 262 </table>
 263     <p>This directive can replace, merge or remove HTTP request
 264     headers. The header is modified just before the content handler
 265     is run, allowing incoming headers to be modified. The action it
 266     performs is determined by the first argument. This can be one
 267     of the following values:</p>
 268
 269     <dl>
 270     <dt><code>set</code></dt>
 271     <dd>The request header is set, replacing any previous header
 272     with this name</dd>
 273
 274     <dt><code>append</code></dt>
 275     <dd>The request header is appended to any existing header of the
 276     same name. When a new value is merged onto an existing header
 277     it is separated from the existing header with a comma. This
 278     is the HTTP standard way of giving a header multiple
 279     values.</dd>
 280
 281     <dt><code>add</code></dt>
 282     <dd>The request header is added to the existing set of headers,
 283     even if this header already exists. This can result in two
 284     (or more) headers having the same name. This can lead to
 285     unforeseen consequences, and in general <code>append</code> should be
 286     used instead.</dd>
 287
 288     <dt><code>unset</code></dt>
 289     <dd>The request header of this name is removed, if it exists. If
 290     there are multiple headers of the same name, all will be removed.</dd>
 291     </dl>
 292
 293     <p>This argument is followed by a header name, which can
 294     include the final colon, but it is not required. Case is
 295     ignored. For <code>add</code>, <code>append</code> and
 296     <code>set</code> a <var>value</var> is given as the third argument. If
 297     <var>value</var> contains spaces, it should be surrounded by double
 298     quotes. For unset, no <var>value</var> should be given.</p>
 299
 300     <p>When the <code class="directive">RequestHeader</code> directive is used with the
 301     <code>add</code>, <code>append</code>, or <code>set</code>
 302     argument, a fourth argument may be used to specify conditions
 303     under which the action will be taken. If the <a href="../env.html">environment variable</a> specified in the
 304     <code>env=...</code> argument exists (or if the environment
 305     variable does not exist and <code>env=!...</code> is specified)
 306     then the action specified by the <code class="directive">RequestHeader</code> directive
 307     will take effect. Otherwise, the directive will have no effect
 308     on the request.</p>
 309
 310     <p>The <code class="directive">RequestHeader</code> directive is processed
 311     just before the request is run by its handler in the fixup phase.
 312     This should allow headers generated by the browser, or by Apache
 313     input filters to be overridden or modified.</p>
 314
 315 </div>
 316 </div>
 317 <div class="bottomlang">
 318 <p><span>Available Languages: </span><a href="../en/mod/mod_headers.html" title="English">&nbsp;en&nbsp;</a> |
 319 <a href="../ko/mod/mod_headers.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
 320 </div><div id="footer">
 321 <p class="apache">Copyright 2009 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>
 322 <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>
 323 </body></html>