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