From: Yann Ylavic <ylavic@apache.org>
Date: Fri, 27 Jan 2023 15:30:46 +0000 (+0000)
Subject: docs: Better mod_proxy_wstunnel vs mod_proxy_http upgrade= documentation.
X-Git-Tag: 2.5.0-alpha2-ci-test-only~136
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b4ac608497b01ad5dcfad2f8f1457115098b3339;p=thirdparty%2Fapache%2Fhttpd.git

docs: Better mod_proxy_wstunnel vs mod_proxy_http upgrade= documentation.

[skip ci]


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

diff --git a/docs/manual/mod/mod_proxy.xml b/docs/manual/mod/mod_proxy.xml
index b0a329c9a74..cf0653cd95a 100644
--- a/docs/manual/mod/mod_proxy.xml
+++ b/docs/manual/mod/mod_proxy.xml
@@ -1275,10 +1275,13 @@ ProxyPass "/example" "http://backend.example.com" max=20 ttl=120 retry=300
         <td><p>Value of secret used by <module>mod_proxy_ajp</module>.
         See the documentation of this module for more details.</p>
     </td></tr>
-    <tr><td>upgrade</td>
+    <tr><td><a id="upgrade" name="upgrade">upgrade</a></td>
         <td>WebSocket</td>
-        <td><p>Protocol accepted in the Upgrade header by <module>mod_proxy_wstunnel</module>.
-        See the documentation of this module for more details.</p>
+        <td><p>Protocol accepted by <module>mod_proxy_http</module> or
+        <module>mod_proxy_wstunnel</module> for the HTTP Upgrade mechanism
+        upon negotiation by the HTTP client/browser (per
+        <a href="https://www.ietf.org/rfc/rfc9110.html#name-upgrade">RFC 9110 - Upgrade</a>).
+        See the <a href="#protoupgrade">Protocol Upgrade</a> note below</p>
     </td></tr>
     <tr><td>mapping</td>
         <td>-</td>
@@ -1500,6 +1503,29 @@ RewriteRule ^/mirror/foo/(.*) %{ENV:protocol}://backend.example.com/$1 [P]
 ProxyPassReverse  "/mirror/foo/" "http://backend.example.com/"
 ProxyPassReverse  "/mirror/foo/" "https://backend.example.com/"
     </highlight>
+
+    <note><title><a id="protoupgrade" name="protoupgrade">Protocol Upgrade</a></title>
+        <p>Since Apache HTTP Server 2.4.47, protocol Upgrade (tunneling) can be handled
+        end-to-end by <module>mod_proxy_http</module> using the <directive>ProxyPass</directive>
+        parameter <var><a href="#upgrade">upgrade</a></var>.</p>
+        <p>End-to-end means that the HTTP Upgrade request from the client/browser is first
+        forwarded by <module>mod_proxy_http</module> to the origin server and the connection
+        will be upgraded (and tunneled by <module>mod_proxy_http</module>) only if the origin
+        server accepts/initiates the upgrade (HTTP response <code>101 Switching Protocols</code>).
+        If the origin server responds with anything else <module>mod_proxy_http</module>
+        will continue forwarding (and enforcing) the HTTP protocol as usual for this
+        connection.</p>
+        <example><title>Example</title>
+        <highlight language="config">
+ProxyPass "/some/http/or/ws/path/" "http://example.com/some/http/or/ws/path/" upgrade=websocket
+        </highlight>
+        </example>
+        <p>For Apache HTTP Server 2.4.46 and earlier (or if
+        <directive module="mod_proxy_wstunnel">ProxyWebsocketFallbackToProxyHttp</directive>
+        from 2.4.48 and later disables <module>mod_proxy_http</module> handling), see the
+        documentation of <module>mod_proxy_wstunnel</module> for how to proxy the WebSocket
+        protocol.</p>
+    </note>
 </usage>
 </directivesynopsis>