]> granicus.if.org Git - apache/blob - docs/manual/mod/mod_headers.html.en
mention that "Header onsuccess" is the default and reword the description
[apache] / docs / manual / mod / mod_headers.html.en
1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
5               This file is generated from xml source: DO NOT EDIT
6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
7       -->
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>
13 <body>
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="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
19 <div id="path">
20 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.3</a> &gt; <a href="./">Modules</a></div>
21 <div id="page-content">
22 <div id="preamble"><h1>Apache Module mod_headers</h1>
23 <div class="toplang">
24 <p><span>Available Languages: </span><a href="../en/mod/mod_headers.html" title="English">&nbsp;en&nbsp;</a> |
25 <a href="../ja/mod/mod_headers.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
26 <a href="../ko/mod/mod_headers.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
27 </div>
28 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Customization of HTTP request and response
29 headers</td></tr>
30 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
31 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>headers_module</td></tr>
32 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_headers.c</td></tr></table>
33 <h3>Summary</h3>
34
35     <p>This module provides directives to control and modify HTTP
36     request and response headers. Headers can be merged, replaced
37     or removed.</p>
38 </div>
39 <div id="quickview"><h3 class="directives">Directives</h3>
40 <ul id="toc">
41 <li><img alt="" src="../images/down.gif" /> <a href="#header">Header</a></li>
42 <li><img alt="" src="../images/down.gif" /> <a href="#requestheader">RequestHeader</a></li>
43 </ul>
44 <h3>Topics</h3>
45 <ul id="topics">
46 <li><img alt="" src="../images/down.gif" /> <a href="#order">Order of Processing</a></li>
47 <li><img alt="" src="../images/down.gif" /> <a href="#early">Early and Late Processing</a></li>
48 <li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
49 </ul></div>
50 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
51 <div class="section">
52 <h2><a name="order" id="order">Order of Processing</a></h2>
53
54     <p>The directives provided by <code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code> can
55     occur almost anywhere within the server configuration, and can be
56     limited in scope by enclosing them in <a href="../sections.html">configuration sections</a>.</p>
57
58     <p>Order of processing is important and is affected both by the
59     order in the configuration file and by placement in <a href="../sections.html#mergin">configuration sections</a>. These
60     two directives have a different effect if reversed:</p>
61
62     <div class="example"><p><code>
63       RequestHeader append MirrorID "mirror 12"<br />
64       RequestHeader unset MirrorID
65     </code></p></div>
66
67     <p>This way round, the <code>MirrorID</code> header is not set. If
68     reversed, the MirrorID header is set to "mirror 12".</p>
69 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
70 <div class="section">
71 <h2><a name="early" id="early">Early and Late Processing</a></h2>
72     <p><code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code> can be applied either early or late
73     in the request.  The normal mode is late, when Request Headers are
74     set immediately before running the content generator and Response
75     Headers just as the response is sent down the wire.  Always use
76     Late mode in an operational server.</p>
77
78     <p>Early mode is designed as a test/debugging aid for developers.
79     Directives defined using the <code>early</code> keyword are set
80     right at the beginning of processing the request.  This means
81     they can be used to simulate different requests and set up test
82     cases, but it also means that headers may be changed at any time
83     by other modules before generating a Response.</p>
84
85     <p>Because early directives are processed before the request path's
86     configuration is traversed, early headers can only be set in a
87     main server or virtual host context.  Early directives cannot depend
88     on a request path, so they will fail in contexts such as
89     <code>&lt;Directory&gt;</code> or <code>&lt;Location&gt;</code>.</p>
90 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
91 <div class="section">
92 <h2><a name="examples" id="examples">Examples</a></h2>
93
94     <ol>
95       <li>
96         Copy all request headers that begin with "TS" to the
97         response headers:
98
99         <div class="example"><p><code>
100           Header echo ^TS
101         </code></p></div>
102       </li>
103
104       <li>
105         Add a header, <code>MyHeader</code>, to the response including a
106         timestamp for when the request was received and how long it
107         took to begin serving the request. This header can be used by
108         the client to intuit load on the server or in isolating
109         bottlenecks between the client and the server.
110
111         <div class="example"><p><code>
112           Header set MyHeader "%D %t"
113         </code></p></div>
114
115         <p>results in this header being added to the response:</p>
116
117         <div class="example"><p><code>
118           MyHeader: D=3775428 t=991424704447256
119         </code></p></div>
120       </li>
121
122       <li>
123         Say hello to Joe
124
125         <div class="example"><p><code>
126           Header set MyHeader "Hello Joe. It took %D microseconds \<br />
127           for Apache to serve this request."
128         </code></p></div>
129
130         <p>results in this header being added to the response:</p>
131
132         <div class="example"><p><code>
133           MyHeader: Hello Joe. It took D=3775428 microseconds for Apache
134           to serve this request.
135         </code></p></div>
136       </li>
137
138       <li>
139         Conditionally send <code>MyHeader</code> on the response if and
140         only if header <code>MyRequestHeader</code> is present on the request.
141         This is useful for constructing headers in response to some client
142         stimulus. Note that this example requires the services of the
143         <code class="module"><a href="../mod/mod_setenvif.html">mod_setenvif</a></code> module.
144
145         <div class="example"><p><code>
146           SetEnvIf MyRequestHeader myvalue HAVE_MyRequestHeader<br />
147           Header set MyHeader "%D %t mytext" env=HAVE_MyRequestHeader
148         </code></p></div>
149
150         <p>If the header <code>MyRequestHeader: myvalue</code> is present on
151         the HTTP request, the response will contain the following header:</p>
152
153         <div class="example"><p><code>
154           MyHeader: D=3775428 t=991424704447256 mytext
155         </code></p></div>
156       </li>
157
158       <li>
159         Enable DAV to work with Apache running HTTP through SSL hardware
160         (<a href="http://svn.haxx.se/users/archive-2006-03/0549.shtml">problem
161         description</a>) by replacing <var>https:</var> with
162         <var>http:</var> in the <var>Destination</var> header:
163
164         <div class="example"><p><code>
165           RequestHeader edit Destination ^https: http: early
166         </code></p></div>
167       </li>
168
169       <li>
170         Set the same header value under multiple non-exclusive conditions,
171         but do not duplicate the value in the final header.
172         If all of the following conditions applied to a request (i.e.,
173         if the <code>CGI</code>, <code>NO_CACHE</code> and
174         <code>NO_STORE</code> environment variables all existed for the
175         request):
176
177         <div class="example"><p><code>
178           Header merge Cache-Control no-cache env=CGI<br />
179           Header merge Cache-Control no-cache env=NO_CACHE<br />
180           Header merge Cache-Control no-store env=NO_STORE
181         </code></p></div>
182
183         <p>then the response would contain the following header:</p>
184
185         <div class="example"><p><code>
186           Cache-Control: no-cache, no-store
187         </code></p></div>
188
189         <p>If <code>append</code> was used instead of <code>merge</code>,
190         then the response would contain the following header:</p>
191
192         <div class="example"><p><code>
193           Cache-Control: no-cache, no-cache, no-store
194         </code></p></div>
195       </li>
196       <li>
197         Set a test cookie if and only if the client didn't send us a cookie
198         <div class="example"><p><code>
199           Header set Set-Cookie testcookie !$req{Cookie}
200         </code></p></div>
201       </li>
202     </ol>
203 </div>
204 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
205 <div class="directive-section"><h2><a name="Header" id="Header">Header</a> <a name="header" id="header">Directive</a></h2>
206 <table class="directive">
207 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure HTTP response headers</td></tr>
208 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Header [<var>condition</var>] add|append|echo|edit|merge|set|unset
209 <var>header</var> [<var>value</var>] [early|env=[!]<var>variable</var>]</code></td></tr>
210 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
211 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
212 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
213 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_headers</td></tr>
214 </table>
215     <p>This directive can replace, merge or remove HTTP response
216     headers. The header is modified just after the content handler
217     and output filters are run, allowing outgoing headers to be
218     modified.</p>
219
220     <p>By default, this directive only affects successful responses (responses
221     in the <code>2<var>xx</var></code> range).  The optional <var>condition</var>
222     can be either <code>onsuccess</code> (default) or <code>always</code> (all
223     status codes, including successful responses).  A value of <code>always</code>
224     may be needed to influence headers set by some internal modules even for
225     successful responses, and is always needed to affect non-<code>2<var>xx</var></code> 
226     responses such as redirects or client errors</p>.
227
228     <p>The action it performs is determined by the second
229     argument. This can be one of the following values:</p>
230
231     <dl>
232     <dt><code>add</code></dt>
233     <dd>The response header is added to the existing set of headers,
234     even if this header already exists. This can result in two
235     (or more) headers having the same name. This can lead to
236     unforeseen consequences, and in general <code>set</code>,
237     <code>append</code> or <code>merge</code> should be used instead.</dd>
238
239     <dt><code>append</code></dt>
240     <dd>The response header is appended to any existing header of
241     the same name. When a new value is merged onto an existing
242     header it is separated from the existing header with a comma.
243     This is the HTTP standard way of giving a header multiple values.</dd>
244
245     <dt><code>echo</code></dt>
246     <dd>Request headers with this name are echoed back in the
247     response headers. <var>header</var> may be a
248     <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>.
249     <var>value</var> must be omitted.</dd>
250
251     <dt><code>edit</code></dt>
252     <dd>If this request header exists, its value is transformed according
253     to a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>
254     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>
255     is a replacement string, which may contain backreferences.</dd>
256
257     <dt><code>merge</code></dt>
258     <dd>The response header is appended to any existing header of
259     the same name, unless the value to be appended already appears in the
260     header's comma-delimited list of values.  When a new value is merged onto
261     an existing header it is separated from the existing header with a comma.
262     This is the HTTP standard way of giving a header multiple values.
263     Values are compared in a case sensitive manner, and after
264     all format specifiers have been processed.  Values in double quotes
265     are considered different from otherwise identical unquoted values.</dd>
266
267     <dt><code>set</code></dt>
268     <dd>The response header is set, replacing any previous header
269     with this name. The <var>value</var> may be a format string.</dd>
270
271     <dt><code>unset</code></dt>
272     <dd>The response header of this name is removed, if it exists.
273     If there are multiple headers of the same name, all will be
274     removed. <var>value</var> must be omitted.</dd>
275     </dl>
276
277     <p>This argument is followed by a <var>header</var> name, which
278     can include the final colon, but it is not required. Case is
279     ignored for <code>set</code>, <code>append</code>, <code>merge</code>,
280     <code>add</code>, <code>unset</code> and <code>edit</code>.
281     The <var>header</var> name for <code>echo</code>
282     is case sensitive and may be a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular
283     expression</a>.</p>
284
285     <p>For <code>set</code>, <code>append</code>, <code>merge</code> and
286     <code>add</code> a <var>value</var> is specified as the third argument.
287     If <var>value</var>
288     contains spaces, it should be surrounded by double quotes.
289     <var>value</var> may be a character string, a string containing format
290     specifiers or a combination of both. The following format specifiers
291     are supported in <var>value</var>:</p>
292
293     <table class="bordered"><tr class="header"><th>Format</th><th>Description</th></tr>
294 <tr><td><code>%%</code></td>
295         <td>The percent sign</td></tr>
296 <tr class="odd"><td><code>%t</code></td>
297         <td>The time the request was received in Universal Coordinated Time
298         since the epoch (Jan. 1, 1970) measured in microseconds. The value
299         is preceded by <code>t=</code>.</td></tr>
300 <tr><td><code>%D</code></td>
301         <td>The time from when the request was received to the time the
302         headers are sent on the wire. This is a measure of the duration
303         of the request. The value is preceded by <code>D=</code>.
304         The value is measured in microseconds.</td></tr>
305 <tr class="odd"><td><code>%{VARNAME}e</code></td>
306         <td>The contents of the <a href="../env.html">environment
307         variable</a> <code>VARNAME</code>.</td></tr>
308 <tr><td><code>%{VARNAME}s</code></td>
309         <td>The contents of the <a href="mod_ssl.html#envvars">SSL environment
310         variable</a> <code>VARNAME</code>, if <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is enabled.</td></tr>
311 </table>
312
313     <div class="note"><h3>Note</h3>
314       <p>The <code>%s</code> format specifier is only available in
315       Apache 2.1 and later; it can be used instead of <code>%e</code>
316       to avoid the overhead of enabling <code>SSLOptions
317       +StdEnvVars</code>.  If <code>SSLOptions +StdEnvVars</code> must
318       be enabled anyway for some other reason, <code>%e</code> will be
319       more efficient than <code>%s</code>.</p>
320     </div>
321
322     <p>For <code>edit</code> there is both a <var>value</var> argument
323     which is a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>,
324     and an additional <var>replacement</var> string.</p>
325
326     <p>The <code class="directive">Header</code> directive may be followed by
327     an additional argument, which may be any of:</p>
328     <dl>
329     <dt><code>early</code></dt>
330     <dd>Specifies <a href="#early">early processing</a>.</dd>
331     <dt><code>env=[!]varname</code></dt>
332     <dd>The directive is applied if and only if the <a href="../env.html">environment variable</a> <code>varname</code> exists.
333         A <code>!</code> in front of <code>varname</code> reverses the test,
334         so the directive applies only if <code>varname</code> is unset.</dd>
335     <dt><code>expr</code></dt>
336     <dd>An string that matches neither of the above is parsed as an
337         expression.  Details of expression syntax and evaluation are
338         currently best documented on the <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> page.</dd>
339     </dl>
340
341     <p>Except in <a href="#early">early</a> mode, the
342     <code class="directive">Header</code> directives are processed just
343     before the response is sent to the network. These means that it is
344     possible to set and/or override most headers, except for those headers
345     added by the header filter.</p>
346
347 </div>
348 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
349 <div class="directive-section"><h2><a name="RequestHeader" id="RequestHeader">RequestHeader</a> <a name="requestheader" id="requestheader">Directive</a></h2>
350 <table class="directive">
351 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure HTTP request headers</td></tr>
352 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RequestHeader add|append|edit|merge|set|unset <var>header</var>
353 [<var>value</var>] [<var>replacement</var>] [early|env=[!]<var>variable</var>]</code></td></tr>
354 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
355 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
356 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
357 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_headers</td></tr>
358 </table>
359     <p>This directive can replace, merge, change or remove HTTP request
360     headers. The header is modified just before the content handler
361     is run, allowing incoming headers to be modified. The action it
362     performs is determined by the first argument. This can be one
363     of the following values:</p>
364
365     <dl>
366
367     <dt><code>add</code></dt>
368     <dd>The request header is added to the existing set of headers,
369     even if this header already exists. This can result in two
370     (or more) headers having the same name. This can lead to
371     unforeseen consequences, and in general <code>set</code>,
372     <code>append</code> or <code>merge</code> should be used instead.</dd>
373
374     <dt><code>append</code></dt>
375     <dd>The request header is appended to any existing header of the
376     same name. When a new value is merged onto an existing header
377     it is separated from the existing header with a comma. This
378     is the HTTP standard way of giving a header multiple
379     values.</dd>
380
381     <dt><code>edit</code></dt>
382     <dd>If this request header exists, its value is transformed according
383     to a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a>
384     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>
385     is a replacement string, which may contain backreferences.</dd>
386
387     <dt><code>merge</code></dt>
388     <dd>The response header is appended to any existing header of
389     the same name, unless the value to be appended already appears in the
390     existing header's comma-delimited list of values.  When a new value is
391     merged onto an existing header it is separated from the existing header
392     with a comma.  This is the HTTP standard way of giving a header multiple
393     values.  Values are compared in a case sensitive manner, and after
394     all format specifiers have been processed.  Values in double quotes
395     are considered different from otherwise identical unquoted values.</dd>
396
397     <dt><code>set</code></dt>
398     <dd>The request header is set, replacing any previous header
399     with this name</dd>
400
401     <dt><code>unset</code></dt>
402     <dd>The request header of this name is removed, if it exists. If
403     there are multiple headers of the same name, all will be removed.
404     <var>value</var> must be omitted.</dd>
405     </dl>
406
407     <p>This argument is followed by a header name, which can
408     include the final colon, but it is not required. Case is
409     ignored. For <code>set</code>, <code>append</code>, <code>merge</code> and
410     <code>add</code> a <var>value</var> is given as the third argument. If a
411     <var>value</var> contains spaces, it should be surrounded by double
412     quotes. For <code>unset</code>, no <var>value</var> should be given.
413     <var>value</var> may be a character string, a string containing format
414     specifiers or a combination of both. The supported format specifiers
415     are the same as for the <code class="directive"><a href="#header">Header</a></code>,
416     please have a look there for details.  For <code>edit</code> both
417     a <var>value</var> and a <var>replacement</var> are required, and are
418     a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular expression</a> and a
419     replacement string respectively.</p>
420
421     <p>The <code class="directive">RequestHeader</code> directive may be followed by
422     an additional argument, which may be any of:</p>
423     <dl>
424     <dt><code>early</code></dt>
425     <dd>Specifies <a href="#early">early processing</a>.</dd>
426     <dt><code>env=[!]varname</code></dt>
427     <dd>The directive is applied if and only if the <a href="../env.html">environment variable</a> <code>varname</code> exists.
428         A <code>!</code> in front of <code>varname</code> reverses the test,
429         so the directive applies only if <code>varname</code> is unset.</dd>
430     <dt><code>expr</code></dt>
431     <dd>An string that matches neither of the above is parsed as an
432         expression.  Details of expression syntax and evaluation are
433         currently best documented on the <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> page.</dd>
434     </dl>
435
436     <p>Except in <a href="#early">early</a> mode, the
437     <code class="directive">RequestHeader</code> directive is processed
438     just before the request is run by its handler in the fixup phase.
439     This should allow headers generated by the browser, or by Apache
440     input filters to be overridden or modified.</p>
441
442 </div>
443 </div>
444 <div class="bottomlang">
445 <p><span>Available Languages: </span><a href="../en/mod/mod_headers.html" title="English">&nbsp;en&nbsp;</a> |
446 <a href="../ja/mod/mod_headers.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
447 <a href="../ko/mod/mod_headers.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
448 </div><div id="footer">
449 <p class="apache">Copyright 2009 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>
450 <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>
451 </body></html>