docs: Better mod_proxy_wstunnel vs mod_proxy_http upgrade= documentation.

docs: Add deprecation note for wstunnel, move Upgrade example up for proxy_http.

docs: move mod_proxy_wstunnel deprecation warning up and warn about ANY/NONE protos.

docs: fix typos. [skip ci]

Merges r1907031, r1907035, r1907038, r1907040 from https://svn.apache.org/repos/asf/httpd/httpd/trunk.

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

diff --git a/docs/manual/mod/mod_proxy.xml b/docs/manual/mod/mod_proxy.xml
index 613491d451a0be2dd1236e6661312c5def963922..dbd85914a601ad81d2e9cec096b249e76ab3fd92 100644 (file)
--- a/docs/manual/mod/mod_proxy.xml
+++ b/docs/manual/mod/mod_proxy.xml
@@ -170,6 +170,11 @@ ProxyVia On
 <Proxy "*">
   Require host internal.example.com
 </Proxy>
+    </highlight>
+    </example>
+    <example><title><a id="wsupgrade" name="wsupgrade">Websocket Upgrade (2.4.47 and later)</a></title>
+    <highlight language="config">
+ProxyPass "/some/ws/capable/path/" "http://example.com/some/ws/capable/path/" upgrade=websocket
     </highlight>
     </example>
     </section> <!-- /examples -->
@@ -1236,10 +1241,13 @@ ProxyPass "/example" "http://backend.example.com" max=20 ttl=120 retry=300
         AJP connection.<br />
         Available in Apache HTTP Server 2.4.42 and later.
     </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>
@@ -1461,6 +1469,26 @@ 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>
+      <p>See <a href="#wsupgrade">Websocket Upgrade (2.4.47 and later)</a> for an example of
+      configuration using <module>mod_proxy_http</module>.</p>
+      <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>
 

diff --git a/docs/manual/mod/mod_proxy_wstunnel.xml b/docs/manual/mod/mod_proxy_wstunnel.xml
index 0dd1c470d9187921ee748a8b1c494886b840802b..b1d3be09e3a0b9eb158523f2e8cd3182e36ad9c0 100644 (file)
--- a/docs/manual/mod/mod_proxy_wstunnel.xml
+++ b/docs/manual/mod/mod_proxy_wstunnel.xml
@@ -31,8 +31,14 @@
 <compatibility>Available in httpd 2.4.5 and later</compatibility>
 
 <summary>
-    <p>This module <em>requires</em> the service of <module
-    >mod_proxy</module>. It provides support for the tunnelling of web
+  <note type="warning"><title><a id="deprecation" name="deprecation">Deprecation</a></title>
+    <p>Since Apache HTTP Server 2.4.47, protocol Upgrade (tunneling) can be better handled by
+    <module>mod_proxy_http</module>.</p>
+    <p>See <a href="mod_proxy.html#protoupgrade">Protocol Upgrade</a>.</p>
+  </note>
+
+    <p>This module <em>requires</em> the service of <module >mod_proxy</module>.
+    It provides support for the tunnelling of web
     socket connections to a backend websockets server. The connection
     is automatically upgraded to a websocket connection:</p>
 
@@ -74,12 +80,18 @@ RewriteRule ^/?(.*) "ws://example.com:9080/$1" [P,L]
 
 <p>Load balancing for multiple backends can be achieved using <module>mod_proxy_balancer</module>.</p>
 
-<p>In fact the module can be used to upgrade to other protocols, you can set the <code>upgrade</code>
-parameter in the <directive type="ProxyPass" module="mod_proxy">ProxyPass</directive>
-directive to allow the module to accept other protocol.
-NONE means you bypass the check for the header but still upgrade to WebSocket.
-ANY means that <code>Upgrade</code> will read in the request headers and use
-in the response <code>Upgrade</code></p>
+<p>
+The module can also be used to upgrade to other protocols than WebSocket, by setting
+the <var><a href="mod_proxy.html#upgrade">upgrade</a></var> parameter in the
+<directive type="ProxyPass" module="mod_proxy">ProxyPass</directive>
+directive to some custom protocol name.
+Special <code>upgrade=NONE</code> and <code>upgrade=ANY</code> values may be used for
+testing/forcing the upgrade but they are <strong>not recommended</strong> in production for
+security reasons.
+<code>NONE</code> means that the check for the header is omitted but still the upgrade/tunneling to
+WebSocket always happens.
+<code>ANY</code> means that the upgrade/tunneling will happen using any protocol asked by the client.
+</p>
 </summary>
 
 <seealso><module>mod_proxy</module></seealso>