From: Luca Toscano Date: Sun, 21 Oct 2018 10:55:37 +0000 (+0000) Subject: documentation rebuild X-Git-Tag: 2.4.38~99 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bd4b99c5f62a868140731be43197009a22dd88df;p=thirdparty%2Fapache%2Fhttpd.git documentation rebuild git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1844476 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_headers.html.en b/docs/manual/mod/mod_headers.html.en index f984d326478..77977c63b4d 100644 --- a/docs/manual/mod/mod_headers.html.en +++ b/docs/manual/mod/mod_headers.html.en @@ -219,7 +219,7 @@ Header merge Cache-Control no-store env=NO_STORE Override:FileInfo Status:Extension Module:mod_headers -Compatibility:SetIfEmpty available in 2.4.7 and later, expr=value +Compatibility:SetIfEmpty available in 2.4.7 and later, expr=value available in 2.4.10 and later

This directive can replace, merge or remove HTTP response @@ -228,16 +228,12 @@ available in 2.4.10 and later modified.

The optional condition argument determines which internal - table of responses headers this directive will operate against. Despite the - name, the default value of onsuccess does not limit - an action to responses with a 2xx status code. Headers set under - this condition are still used when, for example, a request is successfully - proxied or generated by CGI, even when they have generated a failing status code.

- -

When your action is a function of an existing header, you may need to specify - a condition of always, depending on which internal table the - original header was set in. The table that corresponds to always is - used for locally generated error responses as well as successful responses. + table of responses headers this directive will operate against: + onsuccess (default, can be omitted) or always. + The difference between the two lists is that the headers contained in the + latter are added to the response even on error, and persisted across + internal redirects (for example, ErrorDocument handlers). + Note also that repeating this directive with both conditions makes sense in some scenarios because always is not a superset of onsuccess with respect to existing headers:

@@ -246,22 +242,56 @@ available in 2.4.10 and later
  • You're adding a header to a locally generated non-success (non-2xx) response, such as a redirect, in which case only the table corresponding to always is used in the ultimate response.
    • -
  • You're modifying or removing a header generated by a CGI script, - in which case the CGI scripts are in the table corresponding to +
  • You're modifying or removing a header generated by a CGI script + or by mod_proxy_fcgi, + in which case the CGI scripts' headers are in the table corresponding to always and not in the default table.
  • You're modifying or removing a header generated by some piece of the server but that header is not being found by the default onsuccess condition.
    • -

    Separately from the condition parameter described above, you - can limit an action based on HTTP status codes for e.g. proxied or CGI +

    This difference between onsuccess and always is + a feature that resulted as a consequence of how httpd internally stores + headers for a HTTP response, since it does not offer any "normalized" single + list of headers. The main problem that can arise if the following concept + is not kept in mind while writing the configuration is that some HTTP responses + might end up with the same header duplicated (confusing users or sometimes even + HTTP clients). For example, suppose that you have a simple PHP proxy setup with + mod_proxy_fcgi and your backend PHP scripts adds the + X-Foo: bar header to each HTTP response. As described above, + mod_proxy_fcgi uses the always table to store + headers, so a configuration like the following ends up in the wrong result, namely + having the header duplicated with both values:

    + + 
    # X-Foo's value is set in the 'onsuccess' headers table
+Header set X-Foo: baz
    + + +

    To circumvent this limitation, there are some known configuration + patterns that can help, like the following:

    + + 
    # 'onsuccess' can be omitted since it is the default
+Header onsuccess unset X-Foo
+Header always set X-Foo "baz"
    + + +

    Separately from the condition parameter described above, you + can limit an action based on HTTP status codes for e.g. proxied or CGI requests. See the example that uses %{REQUEST_STATUS} in the section above.

    The action it performs is determined by the first argument (second argument if a condition is specified). This can be one of the following values:

    +

    Warning

    +

    Please read the difference between always + and onsuccess headers list described above + before start reading the actions list, since that important + concept still applies. Each action, in fact, works as described + but only on the target headers list.

    +
    +
    add
    The response header is added to the existing set of headers, @@ -346,11 +376,11 @@ available in 2.4.10 and later add a value is specified as the next argument. If value contains spaces, it should be surrounded by double quotes. - value may be a character string, a string containing - mod_headers specific format specifiers (and character + value may be a character string, a string containing + mod_headers specific format specifiers (and character literals), or an ap_expr expression prefixed with expr=

    - +

    The following format specifiers are supported in value:

    @@ -406,15 +436,15 @@ available in 2.4.10 and laterboolean expressions such as <If>:

    • The starting point of the grammar is 'string' rather than 'expr'.
      • -
    • Function calls use the %{funcname:arg} syntax rather than +
    • Function calls use the %{funcname:arg} syntax rather than funcname(arg).
    • Multi-argument functions are not currently accessible from this starting point
      • -
    • Quote the entire parameter, such as +
    • Quote the entire parameter, such as 
      Header set foo-checksum "expr=%{md5:foo}"
      • - +
    @@ -438,7 +468,7 @@ available in 2.4.10 and later documented in the ap_expr documentation. 
    # This delays the evaluation of the condition clause compared to <If>
 Header always set CustomHeader my-value "expr=%{REQUEST_URI} =~ m#^/special_path.php$#"
    - + @@ -446,7 +476,7 @@ Header always set CustomHeader my-value "expr=%{REQUEST_URI} =~ m#^/special_path Header directives are processed just before the response is sent to the network. This means that it is possible to set and/or override most headers, except for some headers - added by the HTTP header filter. Prior to 2.2.12, it was not possible + added by the HTTP header filter. Prior to 2.2.12, it was not possible to change the Content-Type header with this directive.

    @@ -463,7 +493,7 @@ Header always set CustomHeader my-value "expr=%{REQUEST_URI} =~ m#^/special_path -
    FormatDescription
    Override:FileInfo
    Status:Extension
    Module:mod_headers
    Compatibility:SetIfEmpty available in 2.4.7 and later, expr=value +
    Compatibility:SetIfEmpty available in 2.4.7 and later, expr=value available in 2.4.10 and later

    This directive can replace, merge, change or remove HTTP request