Merge r1779927 from trunk:

Reworked and added examples to the HTTPProtocolOptions doc

On #httpd-dev a user gave us some hints about what kind of
things would have been great to see in the HTTPProtocolOptions
directive's documentation, so I tried to apply them all.

I also added some examples taken from http_strict.t and tested
a bit. I didn't follow completely the complete change-set of
the HTTPProtocolOptions directive, so please review the change
and let me know if anything is wrong or missing.


Submitted by: elukey


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1780045 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 93 insertions, 52 deletions

diff --git a/docs/manual/mod/core.xml b/docs/manual/mod/core.xml
index 7a254dff02..0afe34148f 100644
--- a/docs/manual/mod/core.xml
+++ b/docs/manual/mod/core.xml
@@ -1257,61 +1257,102 @@ EnableSendfile On
       >RFC 7230 &sect;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 &sect;9.4 Request Splitting</a> and
-    <a href="https://tools.ietf.org/html/rfc7230#section-9.5"
-      >&sect;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 &sect;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 <directive>ErrorLog</directive>,
-    configured with <directive>LogLevel</directive> <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 &sect;9.4 Request Splitting</a> and
+      <a href="https://tools.ietf.org/html/rfc7230#section-9.5"
+        >&sect;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 &sect;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>
+
+      <note type="warning"><title>Security risks of Unsafe</title>
+        <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>
+      </note>
+
+      <example>
+        <title>Example of a request leading to HTTP 400 with Strict mode</title>
+        # Missing CRLF<br />
+        GET / HTTP/1.0\n\n
+      </example>
+    </dd>
+    <dt>RegisteredMethods|LenientMethods</dt>
+    <dd>
+      <p><a href="https://tools.ietf.org/html/rfc7231#section-4.1"
+           >RFC 7231 &sect;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
+      <directive module="core">RegisterHttpMethod</directive>
+      directive, particularly if the <code>Unsafe</code>
+      option has been toggled.</p>
+
+      <note type="warning"><title>Forward Proxy compatibility</title>
+        <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>
+      </note>
+
+      <example>
+        <title>Example of a request leading to HTTP 501 with LenientMethods mode</title>
+        # 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 />
+      </example>
+      </dd>
+      <dt>Allow0.9|Require1.0</dt>
+      <dd>
+      <p><a href="https://tools.ietf.org/html/rfc2616#section-19.6"
+           >RFC 2616 &sect;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>
+
+      <example>
+        <title>Example of a request leading to HTTP 400 with Require1.0 mode</title>
+        # Unsupported HTTP version<br />
+        GET /\r\n\r\n
+      </example>
+    </dd>
+    </dl>
+    <p>Reviewing the messages logged to the
+    <directive module="core">ErrorLog</directive>, configured with
+    <directive module="core">LogLevel</directive> <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 &sect;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 <directive>RegisterHttpMethod</directive>
-    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 &sect;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>
 </usage>
 </directivesynopsis>