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.5</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.5</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 "expr=-z %{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>
215 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Default condition was temporarily changed to "always" in 2.3.9 and 2.3.10</td></tr>
217 <p>This directive can replace, merge or remove HTTP response
218 headers. The header is modified just after the content handler
219 and output filters are run, allowing outgoing headers to be
222 <p> The optional <var>condition</var> argument determines which internal
223 table of responses headers this directive will operate against. Other
224 components of the server may have stored their response headers in either
225 the table that corresponds to <code>onsuccess</code> or the table that
226 corresponds to <code>always</code>. "Always" in this context refers to
227 whether headers you add will be sent during both a successful and unsucessful
228 response, but if your action is a function of an existing header, you
229 will have to read on for further complications.</p>
231 <p> The default value of <code>onsuccess</code> may need to be changed to
232 <code>always</code> under the circumstances similar to those listed below.
233 Note also that repeating this directive with both conditions makes sense in
234 some scenarios because <code>always</code> is not a superset of
235 <code>onsuccess</code> with respect to existing headers:</p>
238 <li> You're adding a header to a non-success (non-2xx) response, such
239 as a redirect, in which case only the table corresponding to
240 <code>always</code> is used in the ultimate response.</li>
241 <li> You're modifying or removing a header generated by a CGI script,
242 in which case the CGI scripts are in the table corresponding to
243 <code>always</code> and not in the default table.</li>
244 <li> You're modifying or removing a header generated by some piece of
245 the server but that header is not being found by the default
246 <code>onsuccess</code> condition.</li>
249 <p>The action it performs is determined by the first
250 argument (second argument if a <var>condition</var> is specified).
251 This can be one of the following values:</p>
254 <dt><code>add</code></dt>
255 <dd>The response header is added to the existing set of headers,
256 even if this header already exists. This can result in two
257 (or more) headers having the same name. This can lead to
258 unforeseen consequences, and in general <code>set</code>,
259 <code>append</code> or <code>merge</code> should be used instead.</dd>
261 <dt><code>append</code></dt>
262 <dd>The response header is appended to any existing header of
263 the same name. When a new value is merged onto an existing
264 header it is separated from the existing header with a comma.
265 This is the HTTP standard way of giving a header multiple values.</dd>
267 <dt><code>echo</code></dt>
268 <dd>Request headers with this name are echoed back in the
269 response headers. <var>header</var> may be a
270 <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>.
271 <var>value</var> must be omitted.</dd>
273 <dt><code>edit</code></dt>
274 <dd>If this request header exists, its value is transformed according
275 to a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>
276 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>
277 is a replacement string, which may contain backreferences.</dd>
279 <dt><code>merge</code></dt>
280 <dd>The response header is appended to any existing header of
281 the same name, unless the value to be appended already appears in the
282 header's comma-delimited list of values. When a new value is merged onto
283 an existing header it is separated from the existing header with a comma.
284 This is the HTTP standard way of giving a header multiple values.
285 Values are compared in a case sensitive manner, and after
286 all format specifiers have been processed. Values in double quotes
287 are considered different from otherwise identical unquoted values.</dd>
289 <dt><code>set</code></dt>
290 <dd>The response header is set, replacing any previous header
291 with this name. The <var>value</var> may be a format string.</dd>
293 <dt><code>unset</code></dt>
294 <dd>The response header of this name is removed, if it exists.
295 If there are multiple headers of the same name, all will be
296 removed. <var>value</var> must be omitted.</dd>
299 <p>This argument is followed by a <var>header</var> name, which
300 can include the final colon, but it is not required. Case is
301 ignored for <code>set</code>, <code>append</code>, <code>merge</code>,
302 <code>add</code>, <code>unset</code> and <code>edit</code>.
303 The <var>header</var> name for <code>echo</code>
304 is case sensitive and may be a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular
307 <p>For <code>set</code>, <code>append</code>, <code>merge</code> and
308 <code>add</code> a <var>value</var> is specified as the next argument.
310 contains spaces, it should be surrounded by double quotes.
311 <var>value</var> may be a character string, a string containing format
312 specifiers or a combination of both. The following format specifiers
313 are supported in <var>value</var>:</p>
315 <table class="bordered"><tr class="header"><th>Format</th><th>Description</th></tr>
316 <tr><td><code>%%</code></td>
317 <td>The percent sign</td></tr>
318 <tr class="odd"><td><code>%t</code></td>
319 <td>The time the request was received in Universal Coordinated Time
320 since the epoch (Jan. 1, 1970) measured in microseconds. The value
321 is preceded by <code>t=</code>.</td></tr>
322 <tr><td><code>%D</code></td>
323 <td>The time from when the request was received to the time the
324 headers are sent on the wire. This is a measure of the duration
325 of the request. The value is preceded by <code>D=</code>.
326 The value is measured in microseconds.</td></tr>
327 <tr class="odd"><td><code>%{VARNAME}e</code></td>
328 <td>The contents of the <a href="../env.html">environment
329 variable</a> <code>VARNAME</code>.</td></tr>
330 <tr><td><code>%{VARNAME}s</code></td>
331 <td>The contents of the <a href="mod_ssl.html#envvars">SSL environment
332 variable</a> <code>VARNAME</code>, if <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is enabled.</td></tr>
335 <div class="note"><h3>Note</h3>
336 <p>The <code>%s</code> format specifier is only available in
337 Apache 2.1 and later; it can be used instead of <code>%e</code>
338 to avoid the overhead of enabling <code>SSLOptions
339 +StdEnvVars</code>. If <code>SSLOptions +StdEnvVars</code> must
340 be enabled anyway for some other reason, <code>%e</code> will be
341 more efficient than <code>%s</code>.</p>
344 <p>For <code>edit</code> there is both a <var>value</var> argument
345 which is a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>,
346 and an additional <var>replacement</var> string.</p>
348 <p>The <code class="directive">Header</code> directive may be followed by
349 an additional argument, which may be any of:</p>
351 <dt><code>early</code></dt>
352 <dd>Specifies <a href="#early">early processing</a>.</dd>
353 <dt><code>env=[!]<var>varname</var></code></dt>
354 <dd>The directive is applied if and only if the <a href="../env.html">environment variable</a> <code>varname</code> exists.
355 A <code>!</code> in front of <code>varname</code> reverses the test,
356 so the directive applies only if <code>varname</code> is unset.</dd>
357 <dt><code>expr=<var>expression</var></code></dt>
358 <dd>The directive is applied if and only if <var>expression</var>
359 evaluates to true. Details of expression syntax and evaluation are
360 documented in the <a href="../expr.html">ap_expr</a> documentation.</dd>
363 <p>Except in <a href="#early">early</a> mode, the
364 <code class="directive">Header</code> directives are processed just
365 before the response is sent to the network. These means that it is
366 possible to set and/or override most headers, except for those headers
367 added by the HTTP header filter, such as Content-Type.</p>
370 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
371 <div class="directive-section"><h2><a name="RequestHeader" id="RequestHeader">RequestHeader</a> <a name="requestheader" id="requestheader">Directive</a></h2>
372 <table class="directive">
373 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure HTTP request headers</td></tr>
374 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RequestHeader add|append|edit|edit*|merge|set|unset <var>header</var>
375 [<var>value</var>] [<var>replacement</var>] [early|env=[!]<var>variable</var>]</code></td></tr>
376 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
377 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
378 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
379 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_headers</td></tr>
381 <p>This directive can replace, merge, change or remove HTTP request
382 headers. The header is modified just before the content handler
383 is run, allowing incoming headers to be modified. The action it
384 performs is determined by the first argument. This can be one
385 of the following values:</p>
389 <dt><code>add</code></dt>
390 <dd>The request header is added to the existing set of headers,
391 even if this header already exists. This can result in two
392 (or more) headers having the same name. This can lead to
393 unforeseen consequences, and in general <code>set</code>,
394 <code>append</code> or <code>merge</code> should be used instead.</dd>
396 <dt><code>append</code></dt>
397 <dd>The request header is appended to any existing header of the
398 same name. When a new value is merged onto an existing header
399 it is separated from the existing header with a comma. This
400 is the HTTP standard way of giving a header multiple
403 <dt><code>edit</code></dt>
404 <dt><code>edit*</code></dt>
405 <dd>If this request header exists, its value is transformed according
406 to a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>
407 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>
408 is a replacement string, which may contain backreferences.
409 The <code>edit</code> form will match and replace exactly once
410 in a header value, whereas the <code>edit*</code> form will replace
411 <em>every</em> instance of the search pattern if it appears more
414 <dt><code>merge</code></dt>
415 <dd>The response header is appended to any existing header of
416 the same name, unless the value to be appended already appears in the
417 existing header's comma-delimited list of values. When a new value is
418 merged onto an existing header it is separated from the existing header
419 with a comma. This is the HTTP standard way of giving a header multiple
420 values. Values are compared in a case sensitive manner, and after
421 all format specifiers have been processed. Values in double quotes
422 are considered different from otherwise identical unquoted values.</dd>
424 <dt><code>set</code></dt>
425 <dd>The request header is set, replacing any previous header
428 <dt><code>unset</code></dt>
429 <dd>The request header of this name is removed, if it exists. If
430 there are multiple headers of the same name, all will be removed.
431 <var>value</var> must be omitted.</dd>
434 <p>This argument is followed by a header name, which can
435 include the final colon, but it is not required. Case is
436 ignored. For <code>set</code>, <code>append</code>, <code>merge</code> and
437 <code>add</code> a <var>value</var> is given as the third argument. If a
438 <var>value</var> contains spaces, it should be surrounded by double
439 quotes. For <code>unset</code>, no <var>value</var> should be given.
440 <var>value</var> may be a character string, a string containing format
441 specifiers or a combination of both. The supported format specifiers
442 are the same as for the <code class="directive"><a href="#header">Header</a></code>,
443 please have a look there for details. For <code>edit</code> both
444 a <var>value</var> and a <var>replacement</var> are required, and are
445 a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a> and a
446 replacement string respectively.</p>
448 <p>The <code class="directive">RequestHeader</code> directive may be followed by
449 an additional argument, which may be any of:</p>
451 <dt><code>early</code></dt>
452 <dd>Specifies <a href="#early">early processing</a>.</dd>
453 <dt><code>env=[!]<var>varname</var></code></dt>
454 <dd>The directive is applied if and only if the <a href="../env.html">environment variable</a> <code>varname</code> exists.
455 A <code>!</code> in front of <code>varname</code> reverses the test,
456 so the directive applies only if <code>varname</code> is unset.</dd>
457 <dt><code>expr=<var>expression</var></code></dt>
458 <dd>The directive is applied if and only if <var>expression</var>
459 evaluates to true. Details of expression syntax and evaluation are
460 documented in the <a href="../expr.html">ap_expr</a> documentation.</dd>
463 <p>Except in <a href="#early">early</a> mode, the
464 <code class="directive">RequestHeader</code> directive is processed
465 just before the request is run by its handler in the fixup phase.
466 This should allow headers generated by the browser, or by Apache
467 input filters to be overridden or modified.</p>
471 <div class="bottomlang">
472 <p><span>Available Languages: </span><a href="../en/mod/mod_headers.html" title="English"> en </a> |
473 <a href="../fr/mod/mod_headers.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
474 <a href="../ja/mod/mod_headers.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
475 <a href="../ko/mod/mod_headers.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p>
476 </div><div id="footer">
477 <p class="apache">Copyright 2012 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>
478 <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>