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