Documentation rebuild

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1779928 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 87 insertions, 46 deletions

diff --git a/docs/manual/mod/core.html.en b/docs/manual/mod/core.html.en
index fdbf21e4ea..681e6b1798 100644
--- a/docs/manual/mod/core.html.en
+++ b/docs/manual/mod/core.html.en
@@ -2060,56 +2060,97 @@ media type in the HTTP Content-Type header field</td></tr>
     (<a href="https://tools.ietf.org/html/rfc7230#section-3.2">RFC 7230 §3.2</a>), which are now applied by default or using
     the <code>Strict</code> option. Due to legacy modules, applications or
     custom user-agents which must be deprecated the <code>Unsafe</code>
-    option has been added to revert to the legacy behaviors. These rules
-    are applied prior to request processing, so must be configured at the
-    global or default (first) matching virtual host section, by IP/port
-    interface (and not by name) to be honored.</p>
-
-    <p>Prior to the introduction of this directive, the Apache HTTP Server
-    request message parsers were tolerant of a number of forms of input
-    which did not conform to the protocol.
-    <a href="https://tools.ietf.org/html/rfc7230#section-9.4">RFC 7230 §9.4 Request Splitting</a> and
-    <a href="https://tools.ietf.org/html/rfc7230#section-9.5">§9.5 Response Smuggling</a> call out only two of the potential
-    risks of accepting non-conformant request messages, while
-    <a href="https://tools.ietf.org/html/rfc7230#section-3.5">RFC 7230 §3.5</a> "Message Parsing Robustness" identify the
-    risks of accepting obscure whitespace and request message formatting. 
-    As of the introduction of this directive, all grammar rules of the
-    specification are enforced in the default <code>Strict</code> operating
-    mode, and the strict whitespace suggested by section 3.5 is enforced
-    and cannot be relaxed.</p>
-
-    <p>Users are strongly cautioned against toggling the <code>Unsafe</code>
-    mode of operation, particularly on outward-facing, publicly accessible
-    server deployments.  If an interface is required for faulty monitoring
-    or other custom service consumers running on an intranet, users should
-    toggle the Unsafe option only on a specific virtual host configured
-    to service their internal private network.</p>
-
-    <p>Reviewing the messages logged to the <code class="directive">ErrorLog</code>,
-    configured with <code class="directive">LogLevel</code> <code>debug</code> level,
+    option has been added to revert to the legacy behaviors.</p>
+
+    <p>These rules are applied prior to request processing,
+    so must be configured at the global or default (first) matching
+    virtual host section, by IP/port interface (and not by name)
+    to be honored.</p>
+
+    <p>The directive accepts three parameters from the following list
+       of choices, applying the default to the ones not specified:</p>
+
+    <dl>
+    <dt>Strict|Unsafe</dt>
+    <dd>
+      <p>Prior to the introduction of this directive, the Apache HTTP Server
+      request message parsers were tolerant of a number of forms of input
+      which did not conform to the protocol.
+      <a href="https://tools.ietf.org/html/rfc7230#section-9.4">RFC 7230 §9.4 Request Splitting</a> and
+      <a href="https://tools.ietf.org/html/rfc7230#section-9.5">§9.5 Response Smuggling</a> call out only two of the potential
+      risks of accepting non-conformant request messages, while
+      <a href="https://tools.ietf.org/html/rfc7230#section-3.5">RFC 7230 §3.5</a> "Message Parsing Robustness" identify the
+      risks of accepting obscure whitespace and request message formatting. 
+      As of the introduction of this directive, all grammar rules of the
+      specification are enforced in the default <code>Strict</code> operating
+      mode, and the strict whitespace suggested by section 3.5 is enforced
+      and cannot be relaxed.</p>
+
+      <div class="warning"><h3>Security risks of Unsafe</h3>
+        <p>Users are strongly cautioned against toggling the <code>Unsafe</code>
+        mode of operation, particularly on outward-facing, publicly accessible
+        server deployments.  If an interface is required for faulty monitoring
+        or other custom service consumers running on an intranet, users should
+        toggle the Unsafe option only on a specific virtual host configured
+        to service their internal private network.</p>
+      </div>
+
+      <div class="example"><h3>Example of a request leading to HTTP 400 with Strict mode</h3><p><code>
+        
+        # Missing CRLF<br />
+        GET / HTTP/1.0\n\n
+      </code></p></div>
+    </dd>
+    <dt>RegisteredMethods|LenientMethods</dt>
+    <dd>
+      <p><a href="https://tools.ietf.org/html/rfc7231#section-4.1">RFC 7231 §4.1</a> "Request Methods" "Overview" requires that
+      origin servers shall respond with a HTTP 501 status code when an
+      unsupported method is encountered in the request line.
+      This already happens when the <code>LenientMethods</code> option is used,
+      but administrators may wish to toggle the <code>RegisteredMethods</code>
+      option and register any non-standard methods using the
+      <code class="directive"><a href="#registerhttpmethod">RegisterHttpMethod</a></code>
+      directive, particularly if the <code>Unsafe</code>
+      option has been toggled.</p>
+
+      <div class="warning"><h3>Forward Proxy compatibility</h3>
+        <p>The <code>RegisteredMethods</code> option should <strong>not</strong>
+        be toggled for forward proxy hosts, as the methods supported by the
+        origin servers are unknown to the proxy server.</p>
+      </div>
+
+      <div class="example"><h3>Example of a request leading to HTTP 501 with LenientMethods mode</h3><p><code>
+        
+        # Unknown HTTP method<br />
+        WOW / HTTP/1.0\r\n\r\n<br /><br />
+        # Lowercase HTTP method<br />
+        get / HTTP/1.0\r\n\r\n<br />
+      </code></p></div>
+      </dd>
+      <dt>Allow0.9|Require1.0</dt>
+      <dd>
+      <p><a href="https://tools.ietf.org/html/rfc2616#section-19.6">RFC 2616 §19.6</a> "Compatibility With Previous Versions" had
+      encouraged HTTP servers to support legacy HTTP/0.9 requests. RFC 7230
+      supersedes this with "The expectation to support HTTP/0.9 requests has
+      been removed" and offers additional comments in 
+      <a href="https://tools.ietf.org/html/rfc7230#appendix-A">RFC 7230 Appendix A</a>. The <code>Require1.0</code> option allows
+      the user to remove support of the default <code>Allow0.9</code> option's
+      behavior.</p>
+
+      <div class="example"><h3>Example of a request leading to HTTP 400 with Require1.0 mode</h3><p><code>
+        
+        # Unsupported HTTP version<br />
+        GET /\r\n\r\n
+      </code></p></div>
+    </dd>
+    </dl>
+    <p>Reviewing the messages logged to the
+    <code class="directive"><a href="#errorlog">ErrorLog</a></code>, configured with
+    <code class="directive"><a href="#loglevel">LogLevel</a></code> <code>debug</code> level,
     can help identify such faulty requests along with their origin.
     Users should pay particular attention to the 400 responses in the access
     log for invalid requests which were unexpectedly rejected.</p>
 
-    <p><a href="https://tools.ietf.org/html/rfc7231#section-4.1">RFC 7231 §4.1</a> "Request Methods" "Overview" requires that
-    origin servers shall respond with an error when an unsupported method
-    is encountered in the request line. This already happens when the
-    <code>LenientMethods</code> option is used, but administrators may wish
-    to toggle the <code>RegisteredMethods</code> option and register any
-    non-standard methods using the <code class="directive">RegisterHttpMethod</code>
-    directive, particularly if the <code>Unsafe</code> option has been toggled.
-    The <code>RegisteredMethods</code> option should <strong>not</strong>
-    be toggled for forward proxy hosts, as the methods supported by the
-    origin servers are unknown to the proxy server.</p>
-
-    <p><a href="https://tools.ietf.org/html/rfc2616#section-19.6">RFC 2616 §19.6</a> "Compatibility With Previous Versions" had
-    encouraged HTTP servers to support legacy HTTP/0.9 requests. RFC 7230
-    supersedes this with "The expectation to support HTTP/0.9 requests has
-    been removed" and offers additional comments in 
-    <a href="https://tools.ietf.org/html/rfc7230#appendix-A">RFC 7230 Appendix A</a>. The <code>Require1.0</code> option allows
-    the user to remove support of the default <code>Allow0.9</code> option's
-    behavior.</p>
-
 </div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="directive-section"><h2><a name="If" id="If">&lt;If&gt;</a> <a name="if" id="if">Directive</a></h2>