Commit 4ef2c0eb authored by Luca Toscano's avatar Luca Toscano
Browse files

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.



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

docs/manual/mod/core.xml

+93 −52
Original line number Diff line number Diff line
@@ -1280,11 +1280,19 @@ 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>

    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.
@@ -1301,31 +1309,50 @@ EnableSendfile On 
      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>



    <p>Reviewing the messages logged to the <directive>ErrorLog</directive>,

    configured with <directive>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>



      <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 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>

      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
@@ -1335,6 +1362,20 @@ EnableSendfile On 
        >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>

</usage>

</directivesynopsis>