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 Request Headers are
75 set immediately before running the content generator and Response
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 <p>The action it performs is determined by the first
230 argument (second argument if a <var>condition</var> is specified).
231 This can be one of the following values:</p>
234 <dt><code>add</code></dt>
235 <dd>The response header is added to the existing set of headers,
236 even if this header already exists. This can result in two
237 (or more) headers having the same name. This can lead to
238 unforeseen consequences, and in general <code>set</code>,
239 <code>append</code> or <code>merge</code> should be used instead.</dd>
241 <dt><code>append</code></dt>
242 <dd>The response header is appended to any existing header of
243 the same name. When a new value is merged onto an existing
244 header it is separated from the existing header with a comma.
245 This is the HTTP standard way of giving a header multiple values.</dd>
247 <dt><code>echo</code></dt>
248 <dd>Request headers with this name are echoed back in the
249 response headers. <var>header</var> may be a
250 <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>.
251 <var>value</var> must be omitted.</dd>
253 <dt><code>edit</code></dt>
254 <dd>If this request header exists, its value is transformed according
255 to a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>
256 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>
257 is a replacement string, which may contain backreferences.</dd>
259 <dt><code>merge</code></dt>
260 <dd>The response header is appended to any existing header of
261 the same name, unless the value to be appended already appears in the
262 header's comma-delimited list of values. When a new value is merged onto
263 an existing header it is separated from the existing header with a comma.
264 This is the HTTP standard way of giving a header multiple values.
265 Values are compared in a case sensitive manner, and after
266 all format specifiers have been processed. Values in double quotes
267 are considered different from otherwise identical unquoted values.</dd>
269 <dt><code>set</code></dt>
270 <dd>The response header is set, replacing any previous header
271 with this name. The <var>value</var> may be a format string.</dd>
273 <dt><code>unset</code></dt>
274 <dd>The response header of this name is removed, if it exists.
275 If there are multiple headers of the same name, all will be
276 removed. <var>value</var> must be omitted.</dd>
279 <p>This argument is followed by a <var>header</var> name, which
280 can include the final colon, but it is not required. Case is
281 ignored for <code>set</code>, <code>append</code>, <code>merge</code>,
282 <code>add</code>, <code>unset</code> and <code>edit</code>.
283 The <var>header</var> name for <code>echo</code>
284 is case sensitive and may be a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular
287 <p>For <code>set</code>, <code>append</code>, <code>merge</code> and
288 <code>add</code> a <var>value</var> is specified as the next argument.
290 contains spaces, it should be surrounded by double quotes.
291 <var>value</var> may be a character string, a string containing format
292 specifiers or a combination of both. The following format specifiers
293 are supported in <var>value</var>:</p>
295 <table class="bordered"><tr class="header"><th>Format</th><th>Description</th></tr>
296 <tr><td><code>%%</code></td>
297 <td>The percent sign</td></tr>
298 <tr class="odd"><td><code>%t</code></td>
299 <td>The time the request was received in Universal Coordinated Time
300 since the epoch (Jan. 1, 1970) measured in microseconds. The value
301 is preceded by <code>t=</code>.</td></tr>
302 <tr><td><code>%D</code></td>
303 <td>The time from when the request was received to the time the
304 headers are sent on the wire. This is a measure of the duration
305 of the request. The value is preceded by <code>D=</code>.
306 The value is measured in microseconds.</td></tr>
307 <tr class="odd"><td><code>%{VARNAME}e</code></td>
308 <td>The contents of the <a href="../env.html">environment
309 variable</a> <code>VARNAME</code>.</td></tr>
310 <tr><td><code>%{VARNAME}s</code></td>
311 <td>The contents of the <a href="mod_ssl.html#envvars">SSL environment
312 variable</a> <code>VARNAME</code>, if <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is enabled.</td></tr>
315 <div class="note"><h3>Note</h3>
316 <p>The <code>%s</code> format specifier is only available in
317 Apache 2.1 and later; it can be used instead of <code>%e</code>
318 to avoid the overhead of enabling <code>SSLOptions
319 +StdEnvVars</code>. If <code>SSLOptions +StdEnvVars</code> must
320 be enabled anyway for some other reason, <code>%e</code> will be
321 more efficient than <code>%s</code>.</p>
324 <p>For <code>edit</code> there is both a <var>value</var> argument
325 which is a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>,
326 and an additional <var>replacement</var> string.</p>
328 <p>The <code class="directive">Header</code> directive may be followed by
329 an additional argument, which may be any of:</p>
331 <dt><code>early</code></dt>
332 <dd>Specifies <a href="#early">early processing</a>.</dd>
333 <dt><code>env=[!]varname</code></dt>
334 <dd>The directive is applied if and only if the <a href="../env.html">environment variable</a> <code>varname</code> exists.
335 A <code>!</code> in front of <code>varname</code> reverses the test,
336 so the directive applies only if <code>varname</code> is unset.</dd>
337 <dt><code>expr</code></dt>
338 <dd>An string that matches neither of the above is parsed as an
339 expression. Details of expression syntax and evaluation are
340 currently best documented on the <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> page.</dd>
343 <p>Except in <a href="#early">early</a> mode, the
344 <code class="directive">Header</code> directives are processed just
345 before the response is sent to the network. These means that it is
346 possible to set and/or override most headers, except for those headers
347 added by the header filter.</p>
350 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
351 <div class="directive-section"><h2><a name="RequestHeader" id="RequestHeader">RequestHeader</a> <a name="requestheader" id="requestheader">Directive</a></h2>
352 <table class="directive">
353 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure HTTP request headers</td></tr>
354 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RequestHeader add|append|edit|edit*|merge|set|unset <var>header</var>
355 [<var>value</var>] [<var>replacement</var>] [early|env=[!]<var>variable</var>]</code></td></tr>
356 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
357 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
358 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
359 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_headers</td></tr>
361 <p>This directive can replace, merge, change or remove HTTP request
362 headers. The header is modified just before the content handler
363 is run, allowing incoming headers to be modified. The action it
364 performs is determined by the first argument. This can be one
365 of the following values:</p>
369 <dt><code>add</code></dt>
370 <dd>The request header is added to the existing set of headers,
371 even if this header already exists. This can result in two
372 (or more) headers having the same name. This can lead to
373 unforeseen consequences, and in general <code>set</code>,
374 <code>append</code> or <code>merge</code> should be used instead.</dd>
376 <dt><code>append</code></dt>
377 <dd>The request header is appended to any existing header of the
378 same name. When a new value is merged onto an existing header
379 it is separated from the existing header with a comma. This
380 is the HTTP standard way of giving a header multiple
383 <dt><code>edit</code></dt>
384 <dt><code>edit*</code></dt>
385 <dd>If this request header exists, its value is transformed according
386 to a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>
387 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>
388 is a replacement string, which may contain backreferences.
389 The <code>edit</code> form will match and replace exactly once
390 in a header value, whereas the <code>edit*</code> form will replace
391 <em>every</em> instance of the search pattern if it appears more
394 <dt><code>merge</code></dt>
395 <dd>The response header is appended to any existing header of
396 the same name, unless the value to be appended already appears in the
397 existing header's comma-delimited list of values. When a new value is
398 merged onto an existing header it is separated from the existing header
399 with a comma. This is the HTTP standard way of giving a header multiple
400 values. Values are compared in a case sensitive manner, and after
401 all format specifiers have been processed. Values in double quotes
402 are considered different from otherwise identical unquoted values.</dd>
404 <dt><code>set</code></dt>
405 <dd>The request header is set, replacing any previous header
408 <dt><code>unset</code></dt>
409 <dd>The request header of this name is removed, if it exists. If
410 there are multiple headers of the same name, all will be removed.
411 <var>value</var> must be omitted.</dd>
414 <p>This argument is followed by a header name, which can
415 include the final colon, but it is not required. Case is
416 ignored. For <code>set</code>, <code>append</code>, <code>merge</code> and
417 <code>add</code> a <var>value</var> is given as the third argument. If a
418 <var>value</var> contains spaces, it should be surrounded by double
419 quotes. For <code>unset</code>, no <var>value</var> should be given.
420 <var>value</var> may be a character string, a string containing format
421 specifiers or a combination of both. The supported format specifiers
422 are the same as for the <code class="directive"><a href="#header">Header</a></code>,
423 please have a look there for details. For <code>edit</code> both
424 a <var>value</var> and a <var>replacement</var> are required, and are
425 a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a> and a
426 replacement string respectively.</p>
428 <p>The <code class="directive">RequestHeader</code> directive may be followed by
429 an additional argument, which may be any of:</p>
431 <dt><code>early</code></dt>
432 <dd>Specifies <a href="#early">early processing</a>.</dd>
433 <dt><code>env=[!]varname</code></dt>
434 <dd>The directive is applied if and only if the <a href="../env.html">environment variable</a> <code>varname</code> exists.
435 A <code>!</code> in front of <code>varname</code> reverses the test,
436 so the directive applies only if <code>varname</code> is unset.</dd>
437 <dt><code>expr</code></dt>
438 <dd>An string that matches neither of the above is parsed as an
439 expression. Details of expression syntax and evaluation are
440 currently best documented on the <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> page.</dd>
443 <p>Except in <a href="#early">early</a> mode, the
444 <code class="directive">RequestHeader</code> directive is processed
445 just before the request is run by its handler in the fixup phase.
446 This should allow headers generated by the browser, or by Apache
447 input filters to be overridden or modified.</p>
451 <div class="bottomlang">
452 <p><span>Available Languages: </span><a href="../en/mod/mod_headers.html" title="English"> en </a> |
453 <a href="../fr/mod/mod_headers.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
454 <a href="../ja/mod/mod_headers.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
455 <a href="../ko/mod/mod_headers.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p>
456 </div><div id="footer">
457 <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>
458 <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>