From: Luca Toscano Date: Sun, 21 Oct 2018 10:55:09 +0000 (+0000) Subject: mod_headers.xml: backport r1844401 X-Git-Tag: 2.4.38~100 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9cb68c4ee13233bf8e36a91cb81cc8874fe5160f;p=thirdparty%2Fapache%2Fhttpd.git mod_headers.xml: backport r1844401 git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1844475 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_headers.xml b/docs/manual/mod/mod_headers.xml index a0c2eca929a..33f3f787aad 100644 --- a/docs/manual/mod/mod_headers.xml +++ b/docs/manual/mod/mod_headers.xml @@ -207,7 +207,7 @@ Header merge Cache-Control no-store env=NO_STORE server configvirtual host directory.htaccess FileInfo -SetIfEmpty available in 2.4.7 and later, expr=value +SetIfEmpty available in 2.4.7 and later, expr=value available in 2.4.10 and later @@ -318,7 +318,7 @@ available in 2.4.10 and later server configvirtual host directory.htaccess FileInfo -SetIfEmpty available in 2.4.7 and later, expr=value +SetIfEmpty available in 2.4.7 and later, expr=value available in 2.4.10 and later @@ -328,16 +328,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:

@@ -346,22 +342,58 @@ 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, @@ -448,11 +480,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:

    @@ -518,16 +550,16 @@ 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}"
      • - +
    @@ -553,7 +585,7 @@ available in 2.4.10 and later # This delays the evaluation of the condition clause compared to <If> Header always set CustomHeader my-value "expr=%{REQUEST_URI} =~ m#^/special_path.php$#" - + @@ -561,7 +593,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.