You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by el...@apache.org on 2018/10/20 09:22:16 UTC
svn commit: r1844402 - in /httpd/httpd/trunk/docs/manual/mod: core.html.en
mod_headers.html.en quickreference.html.en
Author: elukey
Date: Sat Oct 20 09:22:16 2018
New Revision: 1844402
URL: http://svn.apache.org/viewvc?rev=1844402&view=rev
Log:
documentation rebuild
Modified:
httpd/httpd/trunk/docs/manual/mod/core.html.en
httpd/httpd/trunk/docs/manual/mod/mod_headers.html.en
httpd/httpd/trunk/docs/manual/mod/quickreference.html.en
Modified: httpd/httpd/trunk/docs/manual/mod/core.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/core.html.en?rev=1844402&r1=1844401&r2=1844402&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/core.html.en (original)
+++ httpd/httpd/trunk/docs/manual/mod/core.html.en Sat Oct 20 09:22:16 2018
@@ -821,7 +821,7 @@ headers</td></tr>
<div class="directive-section"><h2><a name="DefaultStateDir" id="DefaultStateDir">DefaultStateDir</a> <a name="defaultstatedir" id="defaultstatedir">Directive</a><a title="Permanent link" href="#defaultstatedir" class="permalink">¶</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Base directory for the persistent state files</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DefaultStateeDir <var>directory-path</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DefaultStateDir <var>directory-path</var></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DefaultRuntimeDir DEFAULT_REL_STATEDIR (state/)</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
Modified: httpd/httpd/trunk/docs/manual/mod/mod_headers.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_headers.html.en?rev=1844402&r1=1844401&r2=1844402&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/mod_headers.html.en (original)
+++ httpd/httpd/trunk/docs/manual/mod/mod_headers.html.en Sat Oct 20 09:22:16 2018
@@ -228,16 +228,12 @@ available in 2.4.10 and later</td></tr>
modified.</p>
<p> The optional <var>condition</var> argument determines which internal
- table of responses headers this directive will operate against. Despite the
- name, the default value of <code>onsuccess</code> does <em>not</em> limit
- an <var>action</var> to responses with a 2xx status code. Headers set under
- this condition are still used when, for example, a request is <em>successfully</em>
- proxied or generated by CGI, even when they have generated a failing status code.</p>
-
- <p>When your action is a function of an existing header, you may need to specify
- a condition of <code>always</code>, depending on which internal table the
- original header was set in. The table that corresponds to <code>always</code> is
- used for locally generated error responses as well as successful responses.
+ table of responses headers this directive will operate against:
+ <code>onsuccess</code> (default, can be omitted) or <code>always</code>.
+ 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 <code>always</code> is not a superset of
<code>onsuccess</code> with respect to existing headers:</p>
@@ -246,14 +242,40 @@ available in 2.4.10 and later</td></tr>
<li> 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
<code>always</code> is used in the ultimate response.</li>
- <li> You're modifying or removing a header generated by a CGI script,
- in which case the CGI scripts are in the table corresponding to
+ <li> You're modifying or removing a header generated by a CGI script
+ or by <code class="module"><a href="../mod/mod_proxy_fcgi.html">mod_proxy_fcgi</a></code>,
+ in which case the CGI scripts' headers are in the table corresponding to
<code>always</code> and not in the default table.</li>
<li> You're modifying or removing a header generated by some piece of
the server but that header is not being found by the default
<code>onsuccess</code> condition.</li>
</ul>
+ <p>This difference between <code>onsuccess</code> and <code>always</code> 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
+ <code class="module"><a href="../mod/mod_proxy_fcgi.html">mod_proxy_fcgi</a></code> and your backend PHP scripts adds the
+ <code>X-Foo: bar</code> header to each HTTP response. As described above,
+ <code class="module"><a href="../mod/mod_proxy_fcgi.html">mod_proxy_fcgi</a></code> uses the <code>always</code> table to store
+ headers, so a configuration like the following ends up in the wrong result, namely
+ having the header duplicated with both values:</p>
+
+ <pre class="prettyprint lang-config"># X-Foo's value is set in the 'onsuccess' headers table
+Header set X-Foo: baz</pre>
+
+
+ <p>To circumvent this limitation, there are some known configuration
+ patterns that can help, like the following:</p>
+
+ <pre class="prettyprint lang-config"># 'onsuccess' can be omitted since it is the default
+Header onsuccess unset X-Foo
+Header always set X-Foo "baz"</pre>
+
+
<p>Separately from the <var>condition</var> 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.</p>
@@ -262,6 +284,14 @@ available in 2.4.10 and later</td></tr>
argument (second argument if a <var>condition</var> is specified).
This can be one of the following values:</p>
+ <div class="warning"><h3>Warning</h3>
+ <p>Please read the difference between <code>always</code>
+ and <code>onsuccess</code> 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.</p>
+ </div>
+
<dl>
<dt><code>add</code></dt>
<dd>The response header is added to the existing set of headers,
Modified: httpd/httpd/trunk/docs/manual/mod/quickreference.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/quickreference.html.en?rev=1844402&r1=1844401&r2=1844402&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/quickreference.html.en (original)
+++ httpd/httpd/trunk/docs/manual/mod/quickreference.html.en Sat Oct 20 09:22:16 2018
@@ -412,7 +412,7 @@ configured</td></tr>
header field for all resources in the current context that have not been
assigned a language-tag by some other means.</td></tr>
<tr><td><a href="core.html#defaultruntimedir">DefaultRuntimeDir <var>directory-path</var></a></td><td> DEFAULT_REL_RUNTIME +</td><td>s</td><td>C</td></tr><tr><td class="descr" colspan="4">Base directory for the server run-time files</td></tr>
-<tr class="odd"><td><a href="core.html#defaultstatedir">DefaultStateeDir <var>directory-path</var></a></td><td></td><td>s</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Base directory for the persistent state files</td></tr>
+<tr class="odd"><td><a href="core.html#defaultstatedir">DefaultStateDir <var>directory-path</var></a></td><td></td><td>s</td><td>C</td></tr><tr class="odd"><td class="descr" colspan="4">Base directory for the persistent state files</td></tr>
<tr><td><a href="core.html#defaulttype">DefaultType <var>media-type|none</var></a></td><td> none </td><td>svdh</td><td>C</td></tr><tr><td class="descr" colspan="4">This directive has no effect other than to emit warnings
if the value is not <code>none</code>. In prior versions, DefaultType
would specify a default media type to assign to response content for