Apache HTTP Server Version 2.4 (original) (raw)

Apache Module mod_proxy_wstunnel

Available Languages: en | fr

Summary

This module requires the service of [mod_proxy](../mod/mod%5Fproxy.html). It provides support for the tunnelling of web socket connections to a backend websockets server. The connection is automatically upgraded to a websocket connection:

HTTP Response

Upgrade: WebSocket Connection: Upgrade

Proxying requests to a websockets server like echo.websocket.org can be done using the[ProxyPass](../mod/mod%5Fproxy.html#proxypass) directive:

ProxyPass "/ws2/" "ws://echo.websocket.org/" ProxyPass "/wss2/" "wss://echo.websocket.org/"

Proxying both HTTP and websockets at the same time, with a specific set of URL's being websocket-only, can be done by specifying the websockets [ProxyPass](../mod/mod%5Fproxy.html#proxypass) directive before the HTTP directive:

ProxyPassMatch ^/(myApp/ws)$ ws://backend.example.com:9080/$1 ProxyPass / http://backend.example.com:9080/

Proxying both HTTP and websockets at the same time, where the websockets URL's are not websocket-only or not known in advance can be done by using the[RewriteRule](../mod/mod%5Frewrite.html#rewriterule) directive to configure the websockets proxying:

ProxyPass / http://example.com:9080/ RewriteEngine on RewriteCond %{HTTP:Upgrade} websocket [NC] RewriteCond %{HTTP:Connection} upgrade [NC] RewriteRule ^/?(.*) "ws://example.com:9080/$1" [P,L]

Load balancing for multiple backends can be achieved using [mod_proxy_balancer](../mod/mod%5Fproxy%5Fbalancer.html).

The module can also be used to upgrade to other protocols than WebSocket, by setting the upgrade parameter in the[ProxyPass](../mod/mod%5Fproxy.html#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.

Comments

Notice:
This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Libera.chat, or sent to our mailing lists.