(<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"><If></a> <a name="if" id="if">Directive</a></h2>
<tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_proxy_http2.c</td></tr></table>
<h3>Summary</h3>
- <p>This module <em>requires</em> the service of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>. It provides the features used for
- proxying HTTP/2 requests. <code class="module"><a href="../mod/mod_proxy_http2.html">mod_proxy_http2</a></code>
- supports HTTP/2 only. It does <em>not</em>
- provide any downgrades to HTTP/1.1.</p>
+ <p><code class="module"><a href="../mod/mod_proxy_http2.html">mod_proxy_http2</a></code>
+ supports HTTP/2 only, it does <em>not</em>
+ provide any downgrades to HTTP/1.1. This means that the backend
+ needs to support HTTP/2 because HTTP/1.1 will not be used instead.</p>
- <p>Thus, in order to get the ability of handling HTTP/2 proxy requests,
+ <p>This module <em>requires</em> the service of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, so in order to get the ability of
+ handling HTTP/2 proxy requests,
<code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> and <code class="module"><a href="../mod/mod_proxy_http2.html">mod_proxy_http2</a></code>
- have to be present in the server.</p>
+ need to be both loaded by the server.</p>
- <p><code class="module"><a href="../mod/mod_proxy_http2.html">mod_proxy_http2</a></code> works with incoming requests
- over HTTP/1.1 and HTTP/2 requests. If <code class="module"><a href="../mod/mod_http2.html">mod_http2</a></code>
- handles the frontend connection, requests against the same HTTP/2
- backend are sent over a single connection, whenever possible.</p>
+ <p><code class="module"><a href="../mod/mod_proxy_http2.html">mod_proxy_http2</a></code> works with incoming fronted requests
+ using HTTP/1.1 or HTTP/2. In both cases, requests proxied
+ to the same backend are sent over a single TCP connection
+ whenever possible (namely when the connection can be re-used).</p>
+
+ <p>Caveat: there will be no attemp to consolidate multiple HTTP/1.1
+ frontend requests (configured to be proxied to the same backend)
+ into HTTP/2 streams belonging to the same HTTP/2 request.
+ Each HTTP/1.1 frontend request will be proxied to the backend using
+ a separate HTTP/2 request (trying to re-use the same TCP connection
+ if possible).</p>
<p>This module relies on <a href="http://nghttp2.org/">libnghttp2</a>
to provide the core http/2 engine.</p>
projects / apache / commitdiff