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
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>
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.3</p>
17 <img alt="" src="../images/feather.gif" /></div>
18 <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
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/">Documentation</a> > <a href="../">Version 2.3</a> > <a href="./">Modules</a></div>
21 <div id="page-content">
22 <div id="preamble"><h1>Apache Module mod_headers</h1>
24 <p><span>Available Languages: </span><a href="../en/mod/mod_headers.html" title="English"> en </a> |
25 <a href="../fr/mod/mod_headers.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
26 <a href="../ja/mod/mod_headers.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
27 <a href="../ko/mod/mod_headers.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p>
29 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Customization of HTTP request and response
31 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
32 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>headers_module</td></tr>
33 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_headers.c</td></tr></table>
36 <p>This module provides directives to control and modify HTTP
37 request and response headers. Headers can be merged, replaced
40 <div id="quickview"><h3 class="directives">Directives</h3>
42 <li><img alt="" src="../images/down.gif" /> <a href="#header">Header</a></li>
43 <li><img alt="" src="../images/down.gif" /> <a href="#requestheader">RequestHeader</a></li>
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>
51 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
53 <h2><a name="order" id="order">Order of Processing</a></h2>
55 <p>The directives provided by <code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code> can
56 occur almost anywhere within the server configuration, and can be
57 limited in scope by enclosing them in <a href="../sections.html">configuration sections</a>.</p>
59 <p>Order of processing is important and is affected both by the
60 order in the configuration file and by placement in <a href="../sections.html#mergin">configuration sections</a>. These
61 two directives have a different effect if reversed:</p>
63 <div class="example"><p><code>
64 RequestHeader append MirrorID "mirror 12"<br />
65 RequestHeader unset MirrorID
68 <p>This way round, the <code>MirrorID</code> header is not set. If
69 reversed, the MirrorID header is set to "mirror 12".</p>
70 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
72 <h2><a name="early" id="early">Early and Late Processing</a></h2>
73 <p><code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code> can be applied either early or late
74 in the request. The normal mode is late, when <em>Request</em> Headers are
75 set immediately before running the content generator and <em>Response</em>
76 Headers just as the response is sent down the wire. Always use
77 Late mode in an operational server.</p>
79 <p>Early mode is designed as a test/debugging aid for developers.
80 Directives defined using the <code>early</code> keyword are set
81 right at the beginning of processing the request. This means
82 they can be used to simulate different requests and set up test
83 cases, but it also means that headers may be changed at any time
84 by other modules before generating a Response.</p>
86 <p>Because early directives are processed before the request path's
87 configuration is traversed, early headers can only be set in a
88 main server or virtual host context. Early directives cannot depend
89 on a request path, so they will fail in contexts such as
90 <code><Directory></code> or <code><Location></code>.</p>
91 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
93 <h2><a name="examples" id="examples">Examples</a></h2>
97 Copy all request headers that begin with "TS" to the
100 <div class="example"><p><code>
106 Add a header, <code>MyHeader</code>, to the response including a
107 timestamp for when the request was received and how long it
108 took to begin serving the request. This header can be used by
109 the client to intuit load on the server or in isolating
110 bottlenecks between the client and the server.
112 <div class="example"><p><code>
113 Header set MyHeader "%D %t"
116 <p>results in this header being added to the response:</p>
118 <div class="example"><p><code>
119 MyHeader: D=3775428 t=991424704447256
126 <div class="example"><p><code>
127 Header set MyHeader "Hello Joe. It took %D microseconds \<br />
128 for Apache to serve this request."
131 <p>results in this header being added to the response:</p>
133 <div class="example"><p><code>
134 MyHeader: Hello Joe. It took D=3775428 microseconds for Apache
135 to serve this request.
140 Conditionally send <code>MyHeader</code> on the response if and
141 only if header <code>MyRequestHeader</code> is present on the request.
142 This is useful for constructing headers in response to some client
143 stimulus. Note that this example requires the services of the
144 <code class="module"><a href="../mod/mod_setenvif.html">mod_setenvif</a></code> module.
146 <div class="example"><p><code>
147 SetEnvIf MyRequestHeader myvalue HAVE_MyRequestHeader<br />
148 Header set MyHeader "%D %t mytext" env=HAVE_MyRequestHeader
151 <p>If the header <code>MyRequestHeader: myvalue</code> is present on
152 the HTTP request, the response will contain the following header:</p>
154 <div class="example"><p><code>
155 MyHeader: D=3775428 t=991424704447256 mytext
160 Enable DAV to work with Apache running HTTP through SSL hardware
161 (<a href="http://svn.haxx.se/users/archive-2006-03/0549.shtml">problem
162 description</a>) by replacing <var>https:</var> with
163 <var>http:</var> in the <var>Destination</var> header:
165 <div class="example"><p><code>
166 RequestHeader edit Destination ^https: http: early
171 Set the same header value under multiple non-exclusive conditions,
172 but do not duplicate the value in the final header.
173 If all of the following conditions applied to a request (i.e.,
174 if the <code>CGI</code>, <code>NO_CACHE</code> and
175 <code>NO_STORE</code> environment variables all existed for the
178 <div class="example"><p><code>
179 Header merge Cache-Control no-cache env=CGI<br />
180 Header merge Cache-Control no-cache env=NO_CACHE<br />
181 Header merge Cache-Control no-store env=NO_STORE
184 <p>then the response would contain the following header:</p>
186 <div class="example"><p><code>
187 Cache-Control: no-cache, no-store
190 <p>If <code>append</code> was used instead of <code>merge</code>,
191 then the response would contain the following header:</p>
193 <div class="example"><p><code>
194 Cache-Control: no-cache, no-cache, no-store
198 Set a test cookie if and only if the client didn't send us a cookie
199 <div class="example"><p><code>
200 Header set Set-Cookie testcookie !$req{Cookie}
205 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
206 <div class="directive-section"><h2><a name="Header" id="Header">Header</a> <a name="header" id="header">Directive</a></h2>
207 <table class="directive">
208 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure HTTP response headers</td></tr>
209 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Header [<var>condition</var>] add|append|echo|edit|merge|set|unset
210 <var>header</var> [<var>value</var>] [early|env=[!]<var>variable</var>]</code></td></tr>
211 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
212 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
213 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
214 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_headers</td></tr>
216 <p>This directive can replace, merge or remove HTTP response
217 headers. The header is modified just after the content handler
218 and output filters are run, allowing outgoing headers to be
221 <p>By default, this directive only affects successful responses (responses
222 in the <code>2<var>xx</var></code> range). The optional <var>condition</var>
223 can be either <code>onsuccess</code> (default) or <code>always</code> (all
224 status codes, including successful responses). A value of <code>always</code>
225 may be needed to influence headers set by some internal modules even for
226 successful responses, and is always needed to affect non-<code>2<var>xx</var></code>
227 responses such as redirects or client errors.</p>
229 <div class="note"><h3>CGI</h3>
230 <p>To manipulate headers set by CGI scripts, it is necessary to specify
231 <code>always</code> for the first parameter.</p>
234 <p>The action it performs is determined by the first
235 argument (second argument if a <var>condition</var> is specified).
236 This can be one of the following values:</p>
239 <dt><code>add</code></dt>
240 <dd>The response header is added to the existing set of headers,
241 even if this header already exists. This can result in two
242 (or more) headers having the same name. This can lead to
243 unforeseen consequences, and in general <code>set</code>,
244 <code>append</code> or <code>merge</code> should be used instead.</dd>
246 <dt><code>append</code></dt>
247 <dd>The response header is appended to any existing header of
248 the same name. When a new value is merged onto an existing
249 header it is separated from the existing header with a comma.
250 This is the HTTP standard way of giving a header multiple values.</dd>
252 <dt><code>echo</code></dt>
253 <dd>Request headers with this name are echoed back in the
254 response headers. <var>header</var> may be a
255 <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>.
256 <var>value</var> must be omitted.</dd>
258 <dt><code>edit</code></dt>
259 <dd>If this request header exists, its value is transformed according
260 to a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>
261 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>
262 is a replacement string, which may contain backreferences.</dd>
264 <dt><code>merge</code></dt>
265 <dd>The response header is appended to any existing header of
266 the same name, unless the value to be appended already appears in the
267 header's comma-delimited list of values. When a new value is merged onto
268 an existing header it is separated from the existing header with a comma.
269 This is the HTTP standard way of giving a header multiple values.
270 Values are compared in a case sensitive manner, and after
271 all format specifiers have been processed. Values in double quotes
272 are considered different from otherwise identical unquoted values.</dd>
274 <dt><code>set</code></dt>
275 <dd>The response header is set, replacing any previous header
276 with this name. The <var>value</var> may be a format string.</dd>
278 <dt><code>unset</code></dt>
279 <dd>The response header of this name is removed, if it exists.
280 If there are multiple headers of the same name, all will be
281 removed. <var>value</var> must be omitted.</dd>
284 <p>This argument is followed by a <var>header</var> name, which
285 can include the final colon, but it is not required. Case is
286 ignored for <code>set</code>, <code>append</code>, <code>merge</code>,
287 <code>add</code>, <code>unset</code> and <code>edit</code>.
288 The <var>header</var> name for <code>echo</code>
289 is case sensitive and may be a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular
292 <p>For <code>set</code>, <code>append</code>, <code>merge</code> and
293 <code>add</code> a <var>value</var> is specified as the next argument.
295 contains spaces, it should be surrounded by double quotes.
296 <var>value</var> may be a character string, a string containing format
297 specifiers or a combination of both. The following format specifiers
298 are supported in <var>value</var>:</p>
300 <table class="bordered"><tr class="header"><th>Format</th><th>Description</th></tr>
301 <tr><td><code>%%</code></td>
302 <td>The percent sign</td></tr>
303 <tr class="odd"><td><code>%t</code></td>
304 <td>The time the request was received in Universal Coordinated Time
305 since the epoch (Jan. 1, 1970) measured in microseconds. The value
306 is preceded by <code>t=</code>.</td></tr>
307 <tr><td><code>%D</code></td>
308 <td>The time from when the request was received to the time the
309 headers are sent on the wire. This is a measure of the duration
310 of the request. The value is preceded by <code>D=</code>.
311 The value is measured in microseconds.</td></tr>
312 <tr class="odd"><td><code>%{VARNAME}e</code></td>
313 <td>The contents of the <a href="../env.html">environment
314 variable</a> <code>VARNAME</code>.</td></tr>
315 <tr><td><code>%{VARNAME}s</code></td>
316 <td>The contents of the <a href="mod_ssl.html#envvars">SSL environment
317 variable</a> <code>VARNAME</code>, if <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is enabled.</td></tr>
320 <div class="note"><h3>Note</h3>
321 <p>The <code>%s</code> format specifier is only available in
322 Apache 2.1 and later; it can be used instead of <code>%e</code>
323 to avoid the overhead of enabling <code>SSLOptions
324 +StdEnvVars</code>. If <code>SSLOptions +StdEnvVars</code> must
325 be enabled anyway for some other reason, <code>%e</code> will be
326 more efficient than <code>%s</code>.</p>
329 <p>For <code>edit</code> there is both a <var>value</var> argument
330 which is a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>,
331 and an additional <var>replacement</var> string.</p>
333 <p>The <code class="directive">Header</code> directive may be followed by
334 an additional argument, which may be any of:</p>
336 <dt><code>early</code></dt>
337 <dd>Specifies <a href="#early">early processing</a>.</dd>
338 <dt><code>env=[!]varname</code></dt>
339 <dd>The directive is applied if and only if the <a href="../env.html">environment variable</a> <code>varname</code> exists.
340 A <code>!</code> in front of <code>varname</code> reverses the test,
341 so the directive applies only if <code>varname</code> is unset.</dd>
342 <dt><code>expr</code></dt>
343 <dd>An string that matches neither of the above is parsed as an
344 expression. Details of expression syntax and evaluation are
345 currently best documented on the <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> page.</dd>
348 <p>Except in <a href="#early">early</a> mode, the
349 <code class="directive">Header</code> directives are processed just
350 before the response is sent to the network. These means that it is
351 possible to set and/or override most headers, except for those headers
352 added by the header filter.</p>
355 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
356 <div class="directive-section"><h2><a name="RequestHeader" id="RequestHeader">RequestHeader</a> <a name="requestheader" id="requestheader">Directive</a></h2>
357 <table class="directive">
358 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure HTTP request headers</td></tr>
359 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RequestHeader add|append|edit|edit*|merge|set|unset <var>header</var>
360 [<var>value</var>] [<var>replacement</var>] [early|env=[!]<var>variable</var>]</code></td></tr>
361 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
362 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
363 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
364 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_headers</td></tr>
366 <p>This directive can replace, merge, change or remove HTTP request
367 headers. The header is modified just before the content handler
368 is run, allowing incoming headers to be modified. The action it
369 performs is determined by the first argument. This can be one
370 of the following values:</p>
374 <dt><code>add</code></dt>
375 <dd>The request header is added to the existing set of headers,
376 even if this header already exists. This can result in two
377 (or more) headers having the same name. This can lead to
378 unforeseen consequences, and in general <code>set</code>,
379 <code>append</code> or <code>merge</code> should be used instead.</dd>
381 <dt><code>append</code></dt>
382 <dd>The request header is appended to any existing header of the
383 same name. When a new value is merged onto an existing header
384 it is separated from the existing header with a comma. This
385 is the HTTP standard way of giving a header multiple
388 <dt><code>edit</code></dt>
389 <dt><code>edit*</code></dt>
390 <dd>If this request header exists, its value is transformed according
391 to a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>
392 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>
393 is a replacement string, which may contain backreferences.
394 The <code>edit</code> form will match and replace exactly once
395 in a header value, whereas the <code>edit*</code> form will replace
396 <em>every</em> instance of the search pattern if it appears more
399 <dt><code>merge</code></dt>
400 <dd>The response header is appended to any existing header of
401 the same name, unless the value to be appended already appears in the
402 existing header's comma-delimited list of values. When a new value is
403 merged onto an existing header it is separated from the existing header
404 with a comma. This is the HTTP standard way of giving a header multiple
405 values. Values are compared in a case sensitive manner, and after
406 all format specifiers have been processed. Values in double quotes
407 are considered different from otherwise identical unquoted values.</dd>
409 <dt><code>set</code></dt>
410 <dd>The request header is set, replacing any previous header
413 <dt><code>unset</code></dt>
414 <dd>The request header of this name is removed, if it exists. If
415 there are multiple headers of the same name, all will be removed.
416 <var>value</var> must be omitted.</dd>
419 <p>This argument is followed by a header name, which can
420 include the final colon, but it is not required. Case is
421 ignored. For <code>set</code>, <code>append</code>, <code>merge</code> and
422 <code>add</code> a <var>value</var> is given as the third argument. If a
423 <var>value</var> contains spaces, it should be surrounded by double
424 quotes. For <code>unset</code>, no <var>value</var> should be given.
425 <var>value</var> may be a character string, a string containing format
426 specifiers or a combination of both. The supported format specifiers
427 are the same as for the <code class="directive"><a href="#header">Header</a></code>,
428 please have a look there for details. For <code>edit</code> both
429 a <var>value</var> and a <var>replacement</var> are required, and are
430 a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a> and a
431 replacement string respectively.</p>
433 <p>The <code class="directive">RequestHeader</code> directive may be followed by
434 an additional argument, which may be any of:</p>
436 <dt><code>early</code></dt>
437 <dd>Specifies <a href="#early">early processing</a>.</dd>
438 <dt><code>env=[!]varname</code></dt>
439 <dd>The directive is applied if and only if the <a href="../env.html">environment variable</a> <code>varname</code> exists.
440 A <code>!</code> in front of <code>varname</code> reverses the test,
441 so the directive applies only if <code>varname</code> is unset.</dd>
442 <dt><code>expr</code></dt>
443 <dd>An string that matches neither of the above is parsed as an
444 expression. Details of expression syntax and evaluation are
445 currently best documented on the <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> page.</dd>
448 <p>Except in <a href="#early">early</a> mode, the
449 <code class="directive">RequestHeader</code> directive is processed
450 just before the request is run by its handler in the fixup phase.
451 This should allow headers generated by the browser, or by Apache
452 input filters to be overridden or modified.</p>
456 <div class="bottomlang">
457 <p><span>Available Languages: </span><a href="../en/mod/mod_headers.html" title="English"> en </a> |
458 <a href="../fr/mod/mod_headers.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
459 <a href="../ja/mod/mod_headers.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
460 <a href="../ko/mod/mod_headers.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p>
461 </div><div id="footer">
462 <p class="apache">Copyright 2010 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>
463 <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>