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 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
   5 <!--
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7               This file is generated from xml source: DO NOT EDIT
   8         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   9       -->
  10 <title>mod_headers - Apache HTTP Server Version 2.5</title>
  11 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  12 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  13 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  14 <script src="../style/scripts/prettify.min.js" type="text/javascript">
  15 </script>
  16
  17 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  18 <body>
  19 <div id="page-header">
  20 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  21 <p class="apache">Apache HTTP Server Version 2.5</p>
  22 <img alt="" src="../images/feather.png" /></div>
  23 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  24 <div id="path">
  25 <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.5</a> &gt; <a href="./">Modules</a></div>
  26 <div id="page-content">
  27 <div id="preamble"><h1>Apache Module mod_headers</h1>
  28 <div class="toplang">
  29 <p><span>Available Languages: </span><a href="../en/mod/mod_headers.html" title="English">&nbsp;en&nbsp;</a> |
  30 <a href="../fr/mod/mod_headers.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
  31 <a href="../ja/mod/mod_headers.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
  32 <a href="../ko/mod/mod_headers.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
  33 </div>
  34 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Customization of HTTP request and response
  35 headers</td></tr>
  36 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  37 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>headers_module</td></tr>
  38 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_headers.c</td></tr></table>
  39 <h3>Summary</h3>
  40
  41     <p>This module provides directives to control and modify HTTP
  42     request and response headers. Headers can be merged, replaced
  43     or removed.</p>
  44 </div>
  45 <div id="quickview"><h3>Topics</h3>
  46 <ul id="topics">
  47 <li><img alt="" src="../images/down.gif" /> <a href="#order">Order of Processing</a></li>
  48 <li><img alt="" src="../images/down.gif" /> <a href="#early">Early and Late Processing</a></li>
  49 <li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
  50 </ul><h3 class="directives">Directives</h3>
  51 <ul id="toc">
  52 <li><img alt="" src="../images/down.gif" /> <a href="#header">Header</a></li>
  53 <li><img alt="" src="../images/down.gif" /> <a href="#requestheader">RequestHeader</a></li>
  54 </ul>
  55 <h3>Bugfix checklist</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">httpd changelog</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&amp;list_id=144532&amp;product=Apache%20httpd-2&amp;query_format=specific&amp;order=changeddate%20DESC%2Cpriority%2Cbug_severity&amp;component=mod_headers">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&amp;component=mod_headers">Report a bug</a></li></ul><h3>See also</h3>
  56 <ul class="seealso">
  57 <li><a href="#comments_section">Comments</a></li></ul></div>
  58 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  59 <div class="section">
  60 <h2><a name="order" id="order">Order of Processing</a></h2>
  61
  62     <p>The directives provided by <code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code> can
  63     occur almost anywhere within the server configuration, and can be
  64     limited in scope by enclosing them in <a href="../sections.html">configuration sections</a>.</p>
  65
  66     <p>Order of processing is important and is affected both by the
  67     order in the configuration file and by placement in <a href="../sections.html#mergin">configuration sections</a>. These
  68     two directives have a different effect if reversed:</p>
  69
  70     <pre class="prettyprint lang-config">RequestHeader append MirrorID "mirror 12"
  71 RequestHeader unset MirrorID</pre>
  72
  73
  74     <p>This way round, the <code>MirrorID</code> header is not set. If
  75     reversed, the MirrorID header is set to "mirror 12".</p>
  76 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  77 <div class="section">
  78 <h2><a name="early" id="early">Early and Late Processing</a></h2>
  79     <p><code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code> can be applied either early or late
  80     in the request.  The normal mode is late, when <em>Request</em> Headers are
  81     set immediately before running the content generator and <em>Response</em>
  82     Headers just as the response is sent down the wire.  Always use
  83     Late mode in an operational server.</p>
  84
  85     <p>Early mode is designed as a test/debugging aid for developers.
  86     Directives defined using the <code>early</code> keyword are set
  87     right at the beginning of processing the request.  This means
  88     they can be used to simulate different requests and set up test
  89     cases, but it also means that headers may be changed at any time
  90     by other modules before generating a Response.</p>
  91
  92     <p>Because early directives are processed before the request path's
  93     configuration is traversed, early headers can only be set in a
  94     main server or virtual host context.  Early directives cannot depend
  95     on a request path, so they will fail in contexts such as
  96     <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> or
  97     <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code>.</p>
  98 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  99 <div class="section">
 100 <h2><a name="examples" id="examples">Examples</a></h2>
 101
 102     <ol>
 103       <li>
 104         Copy all request headers that begin with "TS" to the
 105         response headers:
 106
 107         <pre class="prettyprint lang-config">Header echo ^TS</pre>
 108
 109       </li>
 110
 111       <li>
 112         Add a header, <code>MyHeader</code>, to the response including a
 113         timestamp for when the request was received and how long it
 114         took to begin serving the request. This header can be used by
 115         the client to intuit load on the server or in isolating
 116         bottlenecks between the client and the server.
 117
 118         <pre class="prettyprint lang-config">Header set MyHeader "%D %t"</pre>
 119
 120
 121         <p>results in this header being added to the response:</p>
 122
 123         <div class="example"><p><code>
 124           MyHeader: D=3775428 t=991424704447256
 125         </code></p></div>
 126       </li>
 127
 128       <li>
 129         Say hello to Joe
 130
 131         <pre class="prettyprint lang-config">Header set MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request."</pre>
 132
 133
 134         <p>results in this header being added to the response:</p>
 135
 136         <div class="example"><p><code>
 137           MyHeader: Hello Joe. It took D=3775428 microseconds for Apache
 138           to serve this request.
 139         </code></p></div>
 140       </li>
 141
 142       <li>
 143         Conditionally send <code>MyHeader</code> on the response if and
 144         only if header <code>MyRequestHeader</code> is present on the request.
 145         This is useful for constructing headers in response to some client
 146         stimulus. Note that this example requires the services of the
 147         <code class="module"><a href="../mod/mod_setenvif.html">mod_setenvif</a></code> module.
 148
 149         <pre class="prettyprint lang-config">SetEnvIf MyRequestHeader myvalue HAVE_MyRequestHeader
 150 Header set MyHeader "%D %t mytext" env=HAVE_MyRequestHeader</pre>
 151
 152
 153         <p>If the header <code>MyRequestHeader: myvalue</code> is present on
 154         the HTTP request, the response will contain the following header:</p>
 155
 156         <div class="example"><p><code>
 157           MyHeader: D=3775428 t=991424704447256 mytext
 158         </code></p></div>
 159       </li>
 160
 161       <li>
 162         Enable DAV to work with Apache running HTTP through SSL hardware
 163         (<a href="http://svn.haxx.se/users/archive-2006-03/0549.shtml">problem
 164         description</a>) by replacing <var>https:</var> with
 165         <var>http:</var> in the <var>Destination</var> header:
 166
 167         <pre class="prettyprint lang-config">RequestHeader edit Destination ^https: http: early</pre>
 168
 169       </li>
 170
 171       <li>
 172         Set the same header value under multiple nonexclusive conditions,
 173         but do not duplicate the value in the final header.
 174         If all of the following conditions applied to a request (i.e.,
 175         if the <code>CGI</code>, <code>NO_CACHE</code> and
 176         <code>NO_STORE</code> environment variables all existed for the
 177         request):
 178
 179         <pre class="prettyprint lang-config">Header merge Cache-Control no-cache env=CGI
 180 Header merge Cache-Control no-cache env=NO_CACHE
 181 Header merge Cache-Control no-store env=NO_STORE</pre>
 182
 183
 184         <p>then the response would contain the following header:</p>
 185
 186         <div class="example"><p><code>
 187           Cache-Control: no-cache, no-store
 188         </code></p></div>
 189
 190         <p>If <code>append</code> was used instead of <code>merge</code>,
 191         then the response would contain the following header:</p>
 192
 193         <div class="example"><p><code>
 194           Cache-Control: no-cache, no-cache, no-store
 195         </code></p></div>
 196       </li>
 197       <li>
 198         Set a test cookie if and only if the client didn't send us a cookie
 199         <pre class="prettyprint lang-config">Header set Set-Cookie testcookie "expr=-z %{req:Cookie}"</pre>
 200
 201       </li>
 202       <li>
 203         Append a Caching header for responses with a HTTP status code of 200
 204         <pre class="prettyprint lang-config">Header append Cache-Control s-maxage=600 "expr=%{REQUEST_STATUS} == 200"</pre>
 205
 206       </li>
 207
 208     </ol>
 209 </div>
 210 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 211 <div class="directive-section"><h2><a name="Header" id="Header">Header</a> <a name="header" id="header">Directive</a></h2>
 212 <table class="directive">
 213 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure HTTP response headers</td></tr>
 214 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Header [<var>condition</var>] add|append|echo|edit|edit*|merge|set|setifempty|unset|note
 215 <var>header</var> [[expr=]<var>value</var> [<var>replacement</var>]
 216 [early|env=[!]<var>varname</var>|expr=<var>expression</var>]]
 217 </code></td></tr>
 218 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 219 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 220 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 221 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_headers</td></tr>
 222 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>SetIfEmpty available in 2.4.7 and later, expr=value
 223 available in 2.4.10 and later</td></tr>
 224 </table>
 225     <p>This directive can replace, merge or remove HTTP response
 226     headers. The header is modified just after the content handler
 227     and output filters are run, allowing outgoing headers to be
 228     modified.</p>
 229
 230     <p> The optional <var>condition</var> argument determines which internal
 231     table of responses headers this directive will operate against. Despite the
 232     name, the default value of <code>onsuccess</code> does <em>not</em> limit
 233     an <var>action</var> to responses with a 2xx status code.  Headers set under
 234     this condition are still used when, for example, a request is <em>successfully</em>
 235     proxied or generated by CGI, even when they have generated a failing status code.</p>
 236
 237     <p>When your action is a function of an existing header, you may need to specify
 238     a condition of <code>always</code>, depending on which internal table the
 239     original header was set in.  The table that corresponds to <code>always</code> is
 240     used for locally generated error responses as well as successful responses.
 241     Note also that repeating this directive with both conditions makes sense in
 242     some scenarios because <code>always</code> is not a superset of
 243     <code>onsuccess</code> with respect to existing headers:</p>
 244
 245     <ul>
 246        <li> You're adding a header to a locally generated non-success (non-2xx) response, such
 247             as a redirect, in which case only the table corresponding to
 248             <code>always</code> is used in the ultimate response.</li>
 249        <li> You're modifying or removing a header generated by a CGI script,
 250             in which case the CGI scripts are in the table corresponding to
 251             <code>always</code> and not in the default table.</li>
 252        <li> You're modifying or removing a header generated by some piece of
 253             the server but that header is not being found by the default
 254             <code>onsuccess</code> condition.</li>
 255     </ul>
 256
 257     <p>Separately from the <var>condition</var> parameter described above, you
 258     can limit an action based on HTTP status codes for e.g. proxied or CGI
 259     requests. See the example that uses %{REQUEST_STATUS} in the section above.</p>
 260
 261     <p>The action it performs is determined by the first
 262     argument (second argument if a <var>condition</var> is specified).
 263     This can be one of the following values:</p>
 264
 265     <dl>
 266     <dt><code>add</code></dt>
 267     <dd>The response header is added to the existing set of headers,
 268     even if this header already exists. This can result in two
 269     (or more) headers having the same name. This can lead to
 270     unforeseen consequences, and in general <code>set</code>,
 271     <code>append</code> or <code>merge</code> should be used instead.</dd>
 272
 273     <dt><code>append</code></dt>
 274     <dd>The response header is appended to any existing header of
 275     the same name. When a new value is merged onto an existing
 276     header it is separated from the existing header with a comma.
 277     This is the HTTP standard way of giving a header multiple values.</dd>
 278
 279     <dt><code>echo</code></dt>
 280     <dd>Request headers with this name are echoed back in the
 281     response headers. <var>header</var> may be a
 282     <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>.
 283     <var>value</var> must be omitted.</dd>
 284
 285     <dt><code>edit</code></dt>
 286     <dt><code>edit*</code></dt>
 287     <dd>If this response header exists, its value is transformed according
 288     to a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>
 289     search-and-replace.  The <var>value</var> argument is a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>, and the <var>replacement</var>
 290     is a replacement string, which may contain backreferences or format specifiers.
 291     The <code>edit</code> form will match and replace exactly once
 292     in a header value, whereas the <code>edit*</code> form will replace
 293     <em>every</em> instance of the search pattern if it appears more
 294     than once.</dd>
 295
 296     <dt><code>merge</code></dt>
 297     <dd>The response header is appended to any existing header of
 298     the same name, unless the value to be appended already appears in the
 299     header's comma-delimited list of values.  When a new value is merged onto
 300     an existing header it is separated from the existing header with a comma.
 301     This is the HTTP standard way of giving a header multiple values.
 302     Values are compared in a case sensitive manner, and after
 303     all format specifiers have been processed.  Values in double quotes
 304     are considered different from otherwise identical unquoted values.</dd>
 305
 306     <dt><code>set</code></dt>
 307     <dd>The response header is set, replacing any previous header
 308     with this name. The <var>value</var> may be a format string.</dd>
 309
 310     <dt><code>setifempty</code></dt>
 311     <dd>The request header is set, but only if there is no previous header
 312     with this name.<br />
 313     Available in 2.4.7 and later.</dd>
 314
 315     <dt><code>unset</code></dt>
 316     <dd>The response header of this name is removed, if it exists.
 317     If there are multiple headers of the same name, all will be
 318     removed. <var>value</var> must be omitted.</dd>
 319
 320     <dt><code>note</code></dt>
 321     <dd>The value of the named response <var>header</var> is copied into an
 322     internal note whose name is given by <var>value</var>.  This is useful
 323     if a header sent by a CGI or proxied resource is configured to be unset
 324     but should also be logged.<br />
 325     Available in 2.4.7 and later.</dd>
 326
 327     </dl>
 328
 329     <p>This argument is followed by a <var>header</var> name, which
 330     can include the final colon, but it is not required. Case is
 331     ignored for <code>set</code>, <code>append</code>, <code>merge</code>,
 332     <code>add</code>, <code>unset</code> and <code>edit</code>.
 333     The <var>header</var> name for <code>echo</code>
 334     is case sensitive and may be a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular
 335     expression</a>.</p>
 336
 337     <p>For <code>set</code>, <code>append</code>, <code>merge</code> and
 338     <code>add</code> a <var>value</var> is specified as the next argument.
 339     If <var>value</var>
 340     contains spaces, it should be surrounded by double quotes.
 341     <var>value</var> may be a character string, a string containing
 342     <code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code> specific format specifiers (and character
 343     literals), or an <a href="../expr.html">ap_expr</a> expression prefixed
 344     with <em>expr=</em></p>
 345
 346     <p> The following format specifiers are supported in <var>value</var>:</p>
 347
 348     <table class="bordered"><tr class="header"><th>Format</th><th>Description</th></tr>
 349 <tr><td><code>%%</code></td>
 350         <td>The percent sign</td></tr>
 351 <tr class="odd"><td><code>%t</code></td>
 352         <td>The time the request was received in Universal Coordinated Time
 353         since the epoch (Jan. 1, 1970) measured in microseconds. The value
 354         is preceded by <code>t=</code>.</td></tr>
 355 <tr><td><code>%D</code></td>
 356         <td>The time from when the request was received to the time the
 357         headers are sent on the wire. This is a measure of the duration
 358         of the request. The value is preceded by <code>D=</code>.
 359         The value is measured in microseconds.</td></tr>
 360 <tr class="odd"><td><code>%l</code></td>
 361         <td>The current load averages of the actual server itself. It is
 362         designed to expose the values obtained by <code>getloadavg()</code>
 363         and this represents the current load average, the 5 minute average, and
 364         the 15 minute average. The value is preceded by <code>l=</code> with each
 365         average separated by <code>/</code>.<br />
 366         Available in 2.4.4 and later.
 367         </td></tr>
 368 <tr><td><code>%i</code></td>
 369         <td>The current idle percentage of httpd (0 to 100) based on available
 370         processes and threads. The value is preceded by <code>i=</code>.<br />
 371         Available in 2.4.4 and later.
 372         </td></tr>
 373 <tr class="odd"><td><code>%b</code></td>
 374         <td>The current busy percentage of httpd (0 to 100) based on available
 375         processes and threads. The value is preceded by <code>b=</code>.<br />
 376         Available in 2.4.4 and later.
 377         </td></tr>
 378 <tr><td><code>%{VARNAME}e</code></td>
 379         <td>The contents of the <a href="../env.html">environment
 380         variable</a> <code>VARNAME</code>.</td></tr>
 381 <tr class="odd"><td><code>%{VARNAME}s</code></td>
 382         <td>The contents of the <a href="mod_ssl.html#envvars">SSL environment
 383         variable</a> <code>VARNAME</code>, if <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is enabled.</td></tr>
 384 </table>
 385
 386     <div class="note"><h3>Note</h3>
 387       <p>The <code>%s</code> format specifier is only available in
 388       Apache 2.1 and later; it can be used instead of <code>%e</code>
 389       to avoid the overhead of enabling <code>SSLOptions
 390       +StdEnvVars</code>.  If <code>SSLOptions +StdEnvVars</code> must
 391       be enabled anyway for some other reason, <code>%e</code> will be
 392       more efficient than <code>%s</code>.</p>
 393     </div>
 394
 395     <div class="note"><h3>Note on expression values</h3>
 396     <p> When the value parameter uses the <a href="../expr.html">ap_expr</a>
 397     parser, some expression syntax will differ from examples that evaluate
 398     <em>boolean</em> expressions such as &lt;If&gt;:</p>
 399     <ul>
 400       <li>The starting point of the grammar is 'string' rather than 'expr'.</li>
 401       <li>Function calls use the %{funcname:arg} syntax rather than
 402           funcname(arg).</li>
 403       <li>Multi-argument functions are not currently accessible from this
 404           starting point</li>
 405       <li>Quote the entire parameter, such as
 406           <pre class="prettyprint lang-config">Header set foo-checksum "expr=%{md5:foo}"</pre>
 407
 408        </li>
 409
 410     </ul>
 411     </div>
 412
 413     <p>For <code>edit</code> there is both a <var>value</var> argument
 414     which is a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>,
 415     and an additional <var>replacement</var> string. As of version 2.4.7
 416     the replacement string may also contain format specifiers.</p>
 417
 418     <p>The <code class="directive">Header</code> directive may be followed by
 419     an additional argument, which may be any of:</p>
 420     <dl>
 421     <dt><code>early</code></dt>
 422     <dd>Specifies <a href="#early">early processing</a>.</dd>
 423     <dt><code>env=[!]<var>varname</var></code></dt>
 424     <dd>The directive is applied if and only if the <a href="../env.html">environment variable</a> <code>varname</code> exists.
 425         A <code>!</code> in front of <code>varname</code> reverses the test,
 426         so the directive applies only if <code>varname</code> is unset.</dd>
 427     <dt><code>expr=<var>expression</var></code></dt>
 428     <dd>The directive is applied if and only if <var>expression</var>
 429         evaluates to true. Details of expression syntax and evaluation are
 430         documented in the <a href="../expr.html">ap_expr</a> documentation.
 431         <pre class="prettyprint lang-config"># This delays the evaluation of the condition clause compared to &lt;If&gt;
 432 Header always set CustomHeader my-value "expr=%{REQUEST_URI} =~ m#^/special_path.php$#"</pre>
 433
 434         </dd>
 435     </dl>
 436
 437     <p>Except in <a href="#early">early</a> mode, the
 438     <code class="directive">Header</code> directives are processed just
 439     before the response is sent to the network. This means that it is
 440     possible to set and/or override most headers, except for some headers
 441     added by the HTTP header filter.  Prior to 2.2.12, it was not possible
 442     to change the Content-Type header with this directive.</p>
 443
 444
 445 </div>
 446 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 447 <div class="directive-section"><h2><a name="RequestHeader" id="RequestHeader">RequestHeader</a> <a name="requestheader" id="requestheader">Directive</a></h2>
 448 <table class="directive">
 449 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure HTTP request headers</td></tr>
 450 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RequestHeader add|append|edit|edit*|merge|set|setifempty|unset
 451 <var>header</var> [[expr=]<var>value</var> [<var>replacement</var>]
 452 [early|env=[!]<var>varname</var>|expr=<var>expression</var>]]
 453 </code></td></tr>
 454 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 455 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
 456 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 457 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_headers</td></tr>
 458 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>SetIfEmpty available in 2.4.7 and later, expr=value
 459 available in 2.4.10 and later</td></tr>
 460 </table>
 461     <p>This directive can replace, merge, change or remove HTTP request
 462     headers. The header is modified just before the content handler
 463     is run, allowing incoming headers to be modified. The action it
 464     performs is determined by the first argument. This can be one
 465     of the following values:</p>
 466
 467     <dl>
 468
 469     <dt><code>add</code></dt>
 470     <dd>The request header is added to the existing set of headers,
 471     even if this header already exists. This can result in two
 472     (or more) headers having the same name. This can lead to
 473     unforeseen consequences, and in general <code>set</code>,
 474     <code>append</code> or <code>merge</code> should be used instead.</dd>
 475
 476     <dt><code>append</code></dt>
 477     <dd>The request header is appended to any existing header of the
 478     same name. When a new value is merged onto an existing header
 479     it is separated from the existing header with a comma. This
 480     is the HTTP standard way of giving a header multiple
 481     values.</dd>
 482
 483     <dt><code>edit</code></dt>
 484     <dt><code>edit*</code></dt>
 485     <dd>If this request header exists, its value is transformed according
 486     to a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>
 487     search-and-replace.  The <var>value</var> argument is a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>, and the <var>replacement</var>
 488     is a replacement string, which may contain backreferences or format specifiers.
 489     The <code>edit</code> form will match and replace exactly once
 490     in a header value, whereas the <code>edit*</code> form will replace
 491     <em>every</em> instance of the search pattern if it appears more
 492     than once.</dd>
 493
 494     <dt><code>merge</code></dt>
 495     <dd>The request header is appended to any existing header of
 496     the same name, unless the value to be appended already appears in the
 497     existing header's comma-delimited list of values.  When a new value is
 498     merged onto an existing header it is separated from the existing header
 499     with a comma.  This is the HTTP standard way of giving a header multiple
 500     values.  Values are compared in a case sensitive manner, and after
 501     all format specifiers have been processed.  Values in double quotes
 502     are considered different from otherwise identical unquoted values.</dd>
 503
 504     <dt><code>set</code></dt>
 505     <dd>The request header is set, replacing any previous header
 506     with this name</dd>
 507
 508     <dt><code>setifempty</code></dt>
 509     <dd>The request header is set, but only if there is no previous header
 510     with this name.<br />
 511     Available in 2.4.7 and later.</dd>
 512
 513     <dt><code>unset</code></dt>
 514     <dd>The request header of this name is removed, if it exists. If
 515     there are multiple headers of the same name, all will be removed.
 516     <var>value</var> must be omitted.</dd>
 517     </dl>
 518
 519     <p>This argument is followed by a header name, which can
 520     include the final colon, but it is not required. Case is
 521     ignored. For <code>set</code>, <code>append</code>, <code>merge</code> and
 522     <code>add</code> a <var>value</var> is given as the third argument. If a
 523     <var>value</var> contains spaces, it should be surrounded by double
 524     quotes. For <code>unset</code>, no <var>value</var> should be given.
 525     <var>value</var> may be a character string, a string containing format
 526     specifiers or a combination of both. The supported format specifiers
 527     are the same as for the <code class="directive"><a href="#header">Header</a></code>,
 528     please have a look there for details.  For <code>edit</code> both
 529     a <var>value</var> and a <var>replacement</var> are required, and are
 530     a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a> and a
 531     replacement string respectively.</p>
 532
 533     <p>The <code class="directive">RequestHeader</code> directive may be followed by
 534     an additional argument, which may be any of:</p>
 535     <dl>
 536     <dt><code>early</code></dt>
 537     <dd>Specifies <a href="#early">early processing</a>.</dd>
 538     <dt><code>env=[!]<var>varname</var></code></dt>
 539     <dd>The directive is applied if and only if the <a href="../env.html">environment variable</a> <code>varname</code> exists.
 540         A <code>!</code> in front of <code>varname</code> reverses the test,
 541         so the directive applies only if <code>varname</code> is unset.</dd>
 542     <dt><code>expr=<var>expression</var></code></dt>
 543     <dd>The directive is applied if and only if <var>expression</var>
 544         evaluates to true. Details of expression syntax and evaluation are
 545         documented in the <a href="../expr.html">ap_expr</a> documentation.</dd>
 546     </dl>
 547
 548     <p>Except in <a href="#early">early</a> mode, the
 549     <code class="directive">RequestHeader</code> directive is processed
 550     just before the request is run by its handler in the fixup phase.
 551     This should allow headers generated by the browser, or by Apache
 552     input filters to be overridden or modified.</p>
 553
 554 </div>
 555 </div>
 556 <div class="bottomlang">
 557 <p><span>Available Languages: </span><a href="../en/mod/mod_headers.html" title="English">&nbsp;en&nbsp;</a> |
 558 <a href="../fr/mod/mod_headers.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
 559 <a href="../ja/mod/mod_headers.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
 560 <a href="../ko/mod/mod_headers.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
 561 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
 562 <script type="text/javascript"><!--//--><![CDATA[//><!--
 563 var comments_shortname = 'httpd';
 564 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_headers.html';
 565 (function(w, d) {
 566     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 567         d.write('<div id="comments_thread"><\/div>');
 568         var s = d.createElement('script');
 569         s.type = 'text/javascript';
 570         s.async = true;
 571         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 572         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 573     }
 574     else {
 575         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 576     }
 577 })(window, document);
 578 //--><!]]></script></div><div id="footer">
 579 <p class="apache">Copyright 2016 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>
 580 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
 581 if (typeof(prettyPrint) !== 'undefined') {
 582     prettyPrint();
 583 }
 584 //--><!]]></script>
 585 </body></html>