From: André Malo Date: Thu, 14 Nov 2002 05:28:04 +0000 (+0000) Subject: - -> X-Git-Tag: 2.0.44~60 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=86ceb35f603f0eb956491cbd866c4f3579af68c4;p=apache - -> - reformatting + adding markup - add optional env=[!]variable to formal syntax definition - fix processing order ( after ) - turn bogus
    s to
    - add table border - nothing else ;-) git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@97513 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_headers.xml b/docs/manual/mod/mod_headers.xml index 84ba651e8c..71ab5ab4f0 100644 --- a/docs/manual/mod/mod_headers.xml +++ b/docs/manual/mod/mod_headers.xml @@ -4,12 +4,13 @@ mod_headers -Customization of HTTP request - and response headers +Customization of HTTP request and response +headers Extension mod_headers.c headers_module -RequestHeader is available only in Apache 2.0 +RequestHeader +is available only in Apache 2.0

    This module provides directives to control and modify HTTP @@ -17,92 +18,103 @@ or removed.

     -
    Order of Processing +
    Order of Processing -

    The directives provided by mod_header can occur almost - anywhere within the server configuration. They are valid in the +

    The directives provided by mod_headers can occur + almost anywhere within the server configuration. They are valid in the main server config and virtual host sections, inside - <Directory>, <Location> and <Files> sections, - and within .htaccess files.

    + Directory, + Location and + Files sections, + and within .htaccess files.

    The directives are processed in the following order:

    1. main server
      2. -
    2. virtual host
      3. - -
    3. <Directory> sections and .htaccess
      4. - -
    4. <Location>
      5. - -
    5. <Files>
      6. +
    6. Directory sections and + .htaccess
      7. +
    7. Files
      8. +
    8. Location

    Order is important. These two headers have a different effect if reversed:

    - -RequestHeader append MirrorID "mirror 12"
    - RequestHeader unset MirrorID -     + + 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".

    +

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

    -
    Example +
    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. + Copy all request headers that begin with "TS" to the + response headers: + + + Header echo ^TS* +
      4. -
    4. Say hello to Joe +
    5. + 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" + - - 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. - +

      results in this header being added to the response:

      + + + MyHeader: D=3775428 t=991424704447256 +
      6. -
    6. 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 - +
    7. + 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. + +
      8. + +
    8. + 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 +
    @@ -110,12 +122,10 @@ RequestHeader append MirrorID "mirror 12"
    RequestHeader Configure HTTP request headers -RequestHeader set|append|add|unset header -[value] -server config -virtual host -directory -.htaccess +RequestHeader set|append|add|unset header +[value] +server configvirtual host +directory.htaccess FileInfo @@ -125,37 +135,36 @@ RequestHeader append MirrorID "mirror 12"
    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.
      • -
    +
    +
    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.
    +

    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.

    + 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.

    The RequestHeader directive is processed just before the request is run by its handler in the fixup phase. @@ -167,12 +176,10 @@ RequestHeader append MirrorID "mirror 12"
    Header Configure HTTP response headers -Header set|append|add|unset|echo header -[value] -server config -virtual host -directory -.htaccess +Header set|append|add|unset|echo header +[value [env=[!]variable]] +server configvirtual host +directory.htaccess FileInfo @@ -182,62 +189,62 @@ RequestHeader append MirrorID "mirror 12"
    modified. The action it performs is determined by the first 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.
      • - -
    • echo
      - Request headers with this name are echoed back in the - response headers. header may be a regular - expression.
      • -
    - -

    This argument is followed by a header name, which +

    +
    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.
    + +
    echo
    +
    Request headers with this name are echoed back in the + response headers. header may be a regular expression.
    +
    + +

    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:

    - - - - - - -
    %t: The time the request was received in Universal -Coordinated Time since the epoch (Jan. 1, 1970) measured in -microseconds. The value is preceded by "t=".
    %D: The 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}e: The contents of the environment -variable FOOBAR.
    + 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:

    + + + + + + + + + + +
    %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.

    When the Header directive is used with the add, append, or set @@ -250,10 +257,10 @@ variable FOOBAR. will take effect. Otherwise, the directive will have no effect on the request.

    -

    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.

    +

    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.