From: Yann Ylavic Date: Fri, 27 Jan 2023 18:01:27 +0000 (+0000) Subject: docs: Better mod_proxy_wstunnel vs mod_proxy_http upgrade= documentation. X-Git-Tag: 2.4.56-candidate~33 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ce4538399e784de61ca936d6f5ecd5fdbbfaf8da;p=thirdparty%2Fapache%2Fhttpd.git 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 613491d451a..dbd85914a60 100644 --- 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> + + + <a id="wsupgrade" name="wsupgrade">Websocket Upgrade (2.4.47 and later)</a> + +ProxyPass "/some/ws/capable/path/" "http://example.com/some/ws/capable/path/" upgrade=websocket @@ -1236,10 +1241,13 @@ ProxyPass "/example" "http://backend.example.com" max=20 ttl=120 retry=300 AJP connection.
Available in Apache HTTP Server 2.4.42 and later. - upgrade + upgrade WebSocket -

Protocol accepted in the Upgrade header by mod_proxy_wstunnel. - See the documentation of this module for more details.

+

Protocol accepted by mod_proxy_http or + mod_proxy_wstunnel for the HTTP Upgrade mechanism + upon negotiation by the HTTP client/browser (per + RFC 9110 - Upgrade). + See the Protocol Upgrade note below

mapping - @@ -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/" + + <a id="protoupgrade" name="protoupgrade">Protocol Upgrade</a> +

Since Apache HTTP Server 2.4.47, protocol Upgrade (tunneling) can be handled + end-to-end by mod_proxy_http using the ProxyPass + parameter upgrade.

+

End-to-end means that the HTTP Upgrade request from the client/browser is first + forwarded by mod_proxy_http to the origin server and the connection + will be upgraded (and tunneled by mod_proxy_http) only if the origin + server accepts/initiates the upgrade (HTTP response 101 Switching Protocols). + If the origin server responds with anything else mod_proxy_http + will continue forwarding (and enforcing) the HTTP protocol as usual for this + connection.

+

See Websocket Upgrade (2.4.47 and later) for an example of + configuration using mod_proxy_http.

+

For Apache HTTP Server 2.4.46 and earlier (or if + ProxyWebsocketFallbackToProxyHttp + from 2.4.48 and later disables mod_proxy_http handling), see the + documentation of mod_proxy_wstunnel for how to proxy the WebSocket + protocol.

+ diff --git a/docs/manual/mod/mod_proxy_wstunnel.xml b/docs/manual/mod/mod_proxy_wstunnel.xml index 0dd1c470d91..b1d3be09e3a 100644 --- a/docs/manual/mod/mod_proxy_wstunnel.xml +++ b/docs/manual/mod/mod_proxy_wstunnel.xml @@ -31,8 +31,14 @@ Available in httpd 2.4.5 and later -

This module requires the service of mod_proxy. It provides support for the tunnelling of web + <a id="deprecation" name="deprecation">Deprecation</a> +

Since Apache HTTP Server 2.4.47, protocol Upgrade (tunneling) can be better handled by + mod_proxy_http.

+

See Protocol Upgrade.

+ + +

This module requires the service of mod_proxy. + It provides support for the tunnelling of web socket connections to a backend websockets server. The connection is automatically upgraded to a websocket connection:

@@ -74,12 +80,18 @@ RewriteRule ^/?(.*) "ws://example.com:9080/$1" [P,L]

Load balancing for multiple backends can be achieved using mod_proxy_balancer.

-

In fact the module can be used to upgrade to other protocols, you can set the upgrade -parameter in the ProxyPass -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 Upgrade will read in the request headers and use -in the response Upgrade

+

+The module can also be used to upgrade to other protocols than WebSocket, by setting +the upgrade parameter in the +ProxyPass +directive to some custom protocol name. +Special upgrade=NONE and upgrade=ANY values may be used for +testing/forcing the upgrade but they are not recommended in production for +security reasons. +NONE means that the check for the header is omitted but still the upgrade/tunneling to +WebSocket always happens. +ANY means that the upgrade/tunneling will happen using any protocol asked by the client. +

 mod_proxy