From 595434d8c8fb2a2f6e051f03e8493285e3f1c9db Mon Sep 17 00:00:00 2001 From: Luca Toscano Date: Sat, 20 Oct 2018 09:22:16 +0000 Subject: [PATCH] documentation rebuild git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1844402 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/core.html.en | 2 +- docs/manual/mod/mod_headers.html.en | 54 ++++++++++++++++++++------ docs/manual/mod/quickreference.html.en | 2 +- 3 files changed, 44 insertions(+), 14 deletions(-) diff --git a/docs/manual/mod/core.html.en b/docs/manual/mod/core.html.en index c66ea78d7d..b5f9a03390 100644 --- a/docs/manual/mod/core.html.en +++ b/docs/manual/mod/core.html.en @@ -821,7 +821,7 @@ headers

DefaultStateDir Directive

- + diff --git a/docs/manual/mod/mod_headers.html.en b/docs/manual/mod/mod_headers.html.en index cd8ae6974e..45f5b87b58 100644 --- a/docs/manual/mod/mod_headers.html.en +++ b/docs/manual/mod/mod_headers.html.en @@ -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,14 +242,40 @@ 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.
    • +

    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.

    @@ -262,6 +284,14 @@ available in 2.4.10 and later 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, diff --git a/docs/manual/mod/quickreference.html.en b/docs/manual/mod/quickreference.html.en index 4a6249807f..e4943a3e0c 100644 --- a/docs/manual/mod/quickreference.html.en +++ b/docs/manual/mod/quickreference.html.en @@ -412,7 +412,7 @@ configured header field for all resources in the current context that have not been assigned a language-tag by some other means.
    - +
    Description:Base directory for the persistent state files
    Syntax:DefaultStateeDir directory-path
    Syntax:DefaultStateDir directory-path
    Default:DefaultRuntimeDir DEFAULT_REL_STATEDIR (state/)
    Context:server config
    Status:Core
    DefaultRuntimeDir directory-path DEFAULT_REL_RUNTIME +sC
    Base directory for the server run-time files
    DefaultStateeDir directory-pathsC
    Base directory for the persistent state files
    DefaultStateDir directory-pathsC
    Base directory for the persistent state files
    DefaultType media-type|none none svdhC
    This directive has no effect other than to emit warnings if the value is not none. In prior versions, DefaultType would specify a default media type to assign to response content for -- 2.40.0