From 80db94fff6a9620fb469ee911347ed973e3f7735 Mon Sep 17 00:00:00 2001 From: Stefan Fritsch Date: Tue, 27 Dec 2011 19:42:03 +0100 Subject: Upstream tarball 2.2.3 --- docs/manual/mod/mod_headers.html.en | 356 ++++++++++++++++++++++++++++++++++++ 1 file changed, 356 insertions(+) create mode 100644 docs/manual/mod/mod_headers.html.en (limited to 'docs/manual/mod/mod_headers.html.en') diff --git a/docs/manual/mod/mod_headers.html.en b/docs/manual/mod/mod_headers.html.en new file mode 100644 index 00000000..25c5bc06 --- /dev/null +++ b/docs/manual/mod/mod_headers.html.en @@ -0,0 +1,356 @@ + + + +mod_headers - Apache HTTP Server + + + + + +
+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.2

+
+
<-
+
+Apache > HTTP Server > Documentation > Version 2.2 > Modules
+
+

Apache Module mod_headers

+
+

Available Languages:  en  | + ja  | + ko 

+
+ + + + +
Description:Customization of HTTP request and response +headers
Status:Extension
Module Identifier:headers_module
Source File:mod_headers.c
Compatibility:RequestHeader +is available only in Apache 2.0
+

Summary

+ +

This module provides directives to control and modify HTTP + request and response headers. Headers can be merged, replaced + or removed.

+
+ +
top
+
+

Order of Processing

+ +

The directives provided by mod_headers can + occur almost anywhere within the server configuration, and can be + limited in scope by enclosing them in configuration sections.

+ +

Order of processing is important and is affected both by the + order in the configuration file and by placement in configuration sections. These + two headers have a different effect if reversed:

+ +

+ RequestHeader append MirrorID "mirror 12"
+ RequestHeader unset MirrorID +

+ +

This way round, the MirrorID header is not set. If + reversed, the MirrorID header is set to "mirror 12".

+
top
+
+

Early and Late Processing

+

mod_headers can be applied either early or late + in the request. The normal mode is late, when Request Headers are + set immediately before running the content generator and Response + Headers just as the response is sent down the wire. Always use + Late mode in an operational server.

+ +

Early mode is designed as a test/debugging aid for developers. + Directives defined using the early keyword are set + right at the beginning of processing the request. This means + they can be used to simulate different requests and set up test + cases, but it also means that headers may be changed at any time + by other modules before generating a Response.

+ +

Because early directives are processed before the request path's + configuration is traversed, early headers can only be set in a + main server or virtual host context. Early directives cannot depend + on a request path, so they will fail in contexts such as + <Directory> or <Location>.

+
top
+
+

Examples

+ +
    +
  1. + Copy all request headers that begin with "TS" to the + response headers: + +

    + Header echo ^TS +

    +
    2. + +
  2. + Add a header, MyHeader, to the response including a + timestamp for when the request was received and how long it + took to begin serving the request. This header can be used by + the client to intuit load on the server or in isolating + bottlenecks between the client and the server. + +

    + Header add MyHeader "%D %t" +

    + +

    results in this header being added to the response:

    + +

    + MyHeader: D=3775428 t=991424704447256 +

    +
    3. + +
  3. + Say hello to Joe + +

    + Header add MyHeader "Hello Joe. It took %D microseconds \
    + for Apache to serve this request." +

    + +

    results in this header being added to the response:

    + +

    + MyHeader: Hello Joe. It took D=3775428 microseconds for Apache + to serve this request. +

    +
    4. + +
  4. + Conditionally send MyHeader on the response if and + only if header "MyRequestHeader" is present on the request. This + is useful for constructing headers in response to some client + stimulus. Note that this example requires the services of the + mod_setenvif module. + +

    + SetEnvIf MyRequestHeader value HAVE_MyRequestHeader
    + Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader
    +

    + +

    If the header MyRequestHeader: value is present on + the HTTP request, the response will contain the following header:

    + +

    + MyHeader: D=3775428 t=991424704447256 mytext +

    +
    5. +
+
+
top
+

Header Directive

+ + + + + + + +
Description:Configure HTTP response headers
Syntax:Header [condition] set|append|add|unset|echo +header [value] [early|env=[!]variable]
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Extension
Module:mod_headers
+

This directive can replace, merge or remove HTTP response + headers. The header is modified just after the content handler + and output filters are run, allowing outgoing headers to be + modified.

+ +

The optional condition can be either onsuccess + or always. It determines, which internal header table should be + operated on. onsuccess stands for 2xx + status codes and always for all status codes (including + 2xx). Especially if you want to unset headers + set by certain modules, you should try out, which table is affected.

+ +

The action it performs is determined by the second + argument. This can be one of the following values:

+ +
+
set
+
The response header is set, replacing any previous header + with this name. The value may be a format string.
+ +
append
+
The response header is appended to any existing header of + the same name. When a new value is merged onto an existing + header it is separated from the existing header with a comma. + This is the HTTP standard way of giving a header multiple values.
+ +
add
+
The response header is added to the existing set of headers, + even if this header already exists. This can result in two + (or more) headers having the same name. This can lead to + unforeseen consequences, and in general "append" should be + used instead.
+ +
unset
+
The response header of this name is removed, if it exists. + If there are multiple headers of the same name, all will be + removed. value must be omitted.
+ +
echo
+
Request headers with this name are echoed back in the + response headers. header may be a + regular expression. + value must be omitted.
+
+ +

This argument is followed by a header name, which + can include the final colon, but it is not required. Case is + ignored for set, append, add + and unset. The header name for echo + is case sensitive and may be a regular + expression.

+ +

For add, append and set a + value is specified as the third argument. If value + contains spaces, it should be surrounded by doublequotes. + value may be a character string, a string containing format + specifiers or a combination of both. The following format specifiers + are supported in value:

+ + + + + + + + + + + + +
FormatDescription
%%The percent sign
%tThe time the request was received in Universal Coordinated Time + since the epoch (Jan. 1, 1970) measured in microseconds. The value + is preceded by t=.
%DThe time from when the request was received to the time the + headers are sent on the wire. This is a measure of the duration + of the request. The value is preceded by D=.
%{FOOBAR}eThe contents of the environment + variable FOOBAR.
%{FOOBAR}sThe contents of the SSL environment + variable FOOBAR, if mod_ssl is enabled.
+ +

Note

+

The %s format specifier is only available in + Apache 2.1 and later; it can be used instead of %e + to avoid the overhead of enabling SSLOptions + +StdEnvVars. If SSLOptions +StdEnvVars must + be enabled anyway for some other reason, %e will be + more efficient than %s.

+
+ +

The Header directive may be followed by an + an additional argument, which may be used to specify conditions under + which the action will be taken, or may be the keyword early + to specify early processing. If the + environment variable specified in the + env=... argument exists (or if the environment + variable does not exist and env=!... is specified) + then the action specified by the Header directive + will take effect. Otherwise, the directive will have no effect + on the request.

+ +

Except in early mode, the + Header directives are processed just + before the response is sent to the network. These means that it is + possible to set and/or override most headers, except for those headers + added by the header filter.

+ +
+
top
+

RequestHeader Directive

+ + + + + + + +
Description:Configure HTTP request headers
Syntax:RequestHeader set|append|add|unset header +[value] [early|env=[!]variable]
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Extension
Module:mod_headers
+

This directive can replace, merge or remove HTTP request + headers. The header is modified just before the content handler + is run, allowing incoming headers to be modified. The action it + performs is determined by the first argument. This can be one + of the following values:

+ +
+
set
+
The request header is set, replacing any previous header + with this name
+ +
append
+
The request header is appended to any existing header of the + same name. When a new value is merged onto an existing header + it is separated from the existing header with a comma. This + is the HTTP standard way of giving a header multiple + values.
+ +
add
+
The request header is added to the existing set of headers, + even if this header already exists. This can result in two + (or more) headers having the same name. This can lead to + unforeseen consequences, and in general append should be + used instead.
+ +
unset
+
The request header of this name is removed, if it exists. If + there are multiple headers of the same name, all will be removed. + value must be omitted.
+
+ +

This argument is followed by a header name, which can + include the final colon, but it is not required. Case is + ignored. For add, append and + set a value is given as the third argument. If + value contains spaces, it should be surrounded by double + quotes. For unset, no value should be given. + value may be a character string, a string containing format + specifiers or a combination of both. The supported format specifiers + are the same as for the Header, + please have a look there for details.

+ +

The RequestHeader directive may be followed by + an additional argument, which may be used to specify conditions under + which the action will be taken, or may be the keyword early + to specify early processing. If the + environment + variable specified in the env=... argument + exists (or if the environment variable does not exist and + env=!... is specified) then the action specified + by the RequestHeader directive will take effect. + Otherwise, the directive will have no effect on the request.

+ +

Except in early mode, the + RequestHeader directive is processed + just before the request is run by its handler in the fixup phase. + This should allow headers generated by the browser, or by Apache + input filters to be overridden or modified.

+ +
+
+
+

Available Languages:  en  | + ja  | + ko 

+
+ \ No newline at end of file -- cgit v1.2.3