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       --><title>mod_headers - Apache HTTP Server</title><link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /><link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /><link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link href="../images/favicon.ico" rel="shortcut icon" /></head><body><div id="page-header"><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><p class="apache">Apache HTTP Server Version 2.0</p><img alt="" src="../images/feather.gif" /></div><div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div><div id="path"><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.0</a> &gt; <a href="./">Modules</a></div><div id="page-content"><div id="preamble"><h1>Apache Module mod_headers</h1><table class="module"><tr><th><a href="module-dict.html#Description">Description:
   8                   </a></th><td>Customization of HTTP request
   9     and response headers</td></tr><tr><th><a href="module-dict.html#Status">Status:
  10                   </a></th><td>Extension</td></tr><tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:
  11                   </a></th><td>headers_module</td></tr><tr><th><a href="module-dict.html#SourceFile">Source File:
  12                   </a></th><td>mod_headers.c</td></tr><tr><th><a href="module-dict.html#Compatibility">Compatibility:
  13                   </a></th><td>RequestHeader is available only in Apache 2.0</td></tr></table><h3>Summary</h3>
  14     <p>This module provides directives to control and modify HTTP
  15     request and response headers. Headers can be merged, replaced
  16     or removed.</p>
  17 </div><div id="quickview"><h3 class="directives">Directives</h3><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#header">Header</a></li><li><img alt="" src="../images/down.gif" /> <a href="#requestheader">RequestHeader</a></li></ul><h3>Topics</h3><ul id="topics"><li><img alt="" src="../images/down.gif" /> Order of Processing</li><li><img alt="" src="../images/down.gif" /> Example</li></ul></div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2>Order of Processing</h2>
  18
  19     <p>The directives provided by mod_header can occur almost
  20     anywhere within the server configuration. They are valid in the
  21     main server config and virtual host sections, inside
  22     &lt;Directory&gt;, &lt;Location&gt; and &lt;Files&gt; sections,
  23     and within .htaccess files.</p>
  24
  25     <p>The directives are processed in the following order:</p>
  26
  27     <ol>
  28       <li>main server</li>
  29
  30       <li>virtual host</li>
  31
  32       <li>&lt;Directory&gt; sections and .htaccess</li>
  33
  34       <li>&lt;Location&gt;</li>
  35
  36       <li>&lt;Files&gt;</li>
  37     </ol>
  38
  39     <p>Order is important. These two headers have a different
  40     effect if reversed:</p>
  41
  42 <div class="example"><p><code>
  43 RequestHeader append MirrorID "mirror 12"<br />
  44        RequestHeader unset MirrorID
  45 </code></p></div>
  46
  47     <p>This way round, the MirrorID header is not set. If reversed,
  48     the MirrorID header is set to "mirror 12".</p>
  49 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2>Example</h2>
  50
  51     <ol>
  52       <li>Copy all request headers that begin with "TS" to the
  53       response headers:
  54
  55 <div class="example"><p><code>
  56    Header echo ^TS*
  57 </code></p></div></li>
  58
  59       <li>Add a header, MyHeader, to the response including a
  60       timestamp for when the request was received and how long it
  61       took to begin serving the request. This header can be used by
  62       the client to intuit load on the server or in isolating
  63       bottlenecks between the client and the server.
  64
  65 <div class="example"><p><code>
  66    Header add MyHeader "%D %t"
  67 </code></p></div>
  68         results in this header being added to the response:
  69 <div class="example"><p><code>
  70    MyHeader: D=3775428 t=991424704447256
  71 </code></p></div>
  72       </li>
  73
  74       <li>Say hello to Joe
  75
  76 <div class="example"><p><code>
  77    Header add MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request."
  78 </code></p></div>
  79         results in this header being added to the response:
  80 <div class="example"><p><code>
  81    MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request.
  82 </code></p></div>
  83       </li>
  84
  85       <li>Conditionally send MyHeader on the response if and only
  86       if header "MyRequestHeader" is present on the request. This
  87       is useful for constructing headers in response to some client
  88       stimulus. Note that this example requires the services of the
  89       mod_setenvif module.
  90
  91 <div class="example"><p><code>
  92    SetEnvIf MyRequestHeader value HAVE_MyRequestHeader<br />
  93    Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader
  94 </code></p></div>
  95         If the header "MyRequestHeader: value" is present on the
  96         HTTP request, the response will contain the following
  97         header:
  98 <div class="example"><p><code>
  99    MyHeader: D=3775428 t=991424704447256 mytext
 100 </code></p></div>
 101       </li>
 102     </ol>
 103 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="directive-section"><h2><a name="Header" id="Header">Header</a> <a name="header" id="header">Directive</a></h2><table class="directive"><tr><th><a href="directive-dict.html#Description">Description:
 104               </a></th><td>Configure HTTP response headers</td></tr><tr><th><a href="directive-dict.html#Syntax">Syntax:
 105               </a></th><td>Header set|append|add|unset|echo  <em>header</em>
 106 [<em>value</em>]</td></tr><tr><th><a href="directive-dict.html#Context">Context:
 107               </a></th><td>server config, virtual host, directory, .htaccess</td></tr><tr><th><a href="directive-dict.html#Override">Override:
 108               </a></th><td>FileInfo</td></tr><tr><th><a href="directive-dict.html#Status">Status:
 109               </a></th><td>Extension</td></tr><tr><th><a href="directive-dict.html#Module">Module:
 110               </a></th><td>mod_headers</td></tr></table>
 111     <p>This directive can replace, merge or remove HTTP response
 112     headers. The header is modified just after the content handler
 113     and output filters are run, allowing outgoing headers to be
 114     modified. The action it performs is determined by the first
 115     argument. This can be one of the following values:</p>
 116
 117     <ul>
 118       <li><strong>set</strong><br />
 119        The response header is set, replacing any previous header
 120       with this name. The <em>value</em> may be a format
 121       string.</li>
 122
 123       <li><strong>append</strong><br />
 124        The response header is appended to any existing header of
 125       the same name. When a new value is merged onto an existing
 126       header it is separated from the existing header with a comma.
 127       This is the HTTP standard way of giving a header multiple
 128       values.</li>
 129
 130       <li><strong>add</strong><br />
 131        The response header is added to the existing set of headers,
 132       even if this header already exists. This can result in two
 133       (or more) headers having the same name. This can lead to
 134       unforeseen consequences, and in general "append" should be
 135       used instead.</li>
 136
 137       <li><strong>unset</strong><br />
 138        The response header of this name is removed, if it exists.
 139       If there are multiple headers of the same name, all will be
 140       removed.</li>
 141
 142       <li><strong>echo</strong><br />
 143        Request headers with this name are echoed back in the
 144       response headers. <em>header</em> may be a regular
 145       expression.</li>
 146     </ul>
 147
 148     <p>This argument is followed by a <em>header</em> name, which
 149     can include the final colon, but it is not required. Case is
 150     ignored for set, append, add and unset. The <em>header</em>
 151     name for echo is case sensitive and may be a regular
 152     expression.</p>
 153
 154     <p>For <code>add</code>, <code>append</code> and
 155     <code>set</code> a <em>value</em> is specified as the third
 156     argument. If <em>value</em> contains spaces, it should be
 157     surrounded by doublequotes. <em>value</em> may be a character
 158     string, a string containing format specifiers or a combination
 159     of both. The following format specifiers are supported in
 160     <em>value</em>:</p>
 161 <table>
 162 <tr><td>%t: </td> <td>The time the request was received in Universal
 163 Coordinated Time since the epoch (Jan. 1, 1970) measured in
 164 microseconds. The value is preceded by "t=".</td></tr>
 165
 166 <tr><td>%D: </td> <td>The time from when the request was received to
 167 the time the headers are sent on the wire. This is a measure of the
 168 duration of the request. The value is preceded by "D=".</td></tr>
 169
 170 <tr><td>%{FOOBAR}e:</td> <td>The contents of the <a href="../env.html">environment
 171 variable</a> FOOBAR.</td></tr>
 172 </table>
 173
 174     <p>When the <code class="directive">Header</code> directive is used with the
 175     <code>add</code>, <code>append</code>, or <code>set</code>
 176     argument, a fourth argument may be used to specify conditions
 177     under which the action will be taken. If the <a href="../env.html">environment variable</a> specified in the
 178     <code>env=...</code> argument exists (or if the environment
 179     variable does not exist and <code>env=!...</code> is specified)
 180     then the action specified by the <code class="directive">Header</code> directive
 181     will take effect. Otherwise, the directive will have no effect
 182     on the request.</p>
 183
 184     <p>The Header directives are processed just before the response
 185     is sent to the network. These means that it is possible to set
 186     and/or override most headers, except for those headers added by
 187     the header filter.</p>
 188 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="directive-section"><h2><a name="RequestHeader" id="RequestHeader">RequestHeader</a> <a name="requestheader" id="requestheader">Directive</a></h2><table class="directive"><tr><th><a href="directive-dict.html#Description">Description:
 189               </a></th><td>Configure HTTP request headers</td></tr><tr><th><a href="directive-dict.html#Syntax">Syntax:
 190               </a></th><td>RequestHeader   set|append|add|unset <em>header</em>
 191 [<em>value</em>]</td></tr><tr><th><a href="directive-dict.html#Context">Context:
 192               </a></th><td>server config, virtual host, directory, .htaccess</td></tr><tr><th><a href="directive-dict.html#Override">Override:
 193               </a></th><td>FileInfo</td></tr><tr><th><a href="directive-dict.html#Status">Status:
 194               </a></th><td>Extension</td></tr><tr><th><a href="directive-dict.html#Module">Module:
 195               </a></th><td>mod_headers</td></tr></table>
 196     <p>This directive can replace, merge or remove HTTP request
 197     headers. The header is modified just before the content handler
 198     is run, allowing incoming headers to be modified. The action it
 199     performs is determined by the first argument. This can be one
 200     of the following values:</p>
 201
 202     <ul>
 203       <li><strong>set</strong><br />
 204        The request header is set, replacing any previous header
 205       with this name</li>
 206
 207       <li><strong>append</strong><br />
 208        The request header is appended to any existing header of the
 209       same name. When a new value is merged onto an existing header
 210       it is separated from the existing header with a comma. This
 211       is the HTTP standard way of giving a header multiple
 212       values.</li>
 213
 214       <li><strong>add</strong><br />
 215        The request header is added to the existing set of headers,
 216       even if this header already exists. This can result in two
 217       (or more) headers having the same name. This can lead to
 218       unforeseen consequences, and in general "append" should be
 219       used instead.</li>
 220
 221       <li><strong>unset</strong><br />
 222        The request header of this name is removed, if it exists. If
 223       there are multiple headers of the same name, all will be
 224       removed.</li>
 225     </ul>
 226
 227     <p>This argument is followed by a header name, which can
 228     include the final colon, but it is not required. Case is
 229     ignored. For <code>add</code>, <code>append</code> and
 230     <code>set</code> a <em>value</em> is given as the third argument. If
 231     <em>value</em> contains spaces, it should be surrounded by double
 232     quotes. For unset, no <em>value</em> should be given.</p>
 233
 234     <p>The <code class="directive">RequestHeader</code> directive is processed
 235     just before the request is run by its handler in the fixup phase.
 236     This should allow headers generated by the browser, or by Apache
 237     input filters to be overridden or modified.</p>
 238 </div></div><div id="footer"><p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p><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></body></html>