Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy_wstunnel

Description: Websockets support module for mod_proxy
Status: Extension
Module Identifier: proxy_wstunnel_module
Source File: mod_proxy_wstunnel.c
Compatibility: Available in httpd 2.4.5 and later



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:

HTTP Response

Upgrade: WebSocket
Connection: Upgrade

Proxying requests to a websockets server like echo.websocket.org can be done using the 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 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 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.

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.

Support Apache!


Bugfix checklist

See also


ProxyWebsocketFallbackToProxyHttp Directive

Description: Instructs this module to let mod_proxy_http handle the request
Syntax: ProxyWebsocketFallbackToProxyHttp On|Off
Default: ProxyWebsocketFallbackToProxyHttp On
Context: server config, virtual host
Status: Extension
Module: mod_proxy_wstunnel
Compatibility: Available in httpd 2.4.48 and later

Since httpd 2.4.47, mod_proxy_http can handle WebSocket upgrading and tunneling in accordance to RFC 7230, this directive controls whether mod_proxy_wstunnel should hand over to mod_proxy_http to this, which is the case by default.

Setting to Off lets mod_proxy_wstunnel handle WebSocket requests as in httpd 2.4.46 and earlier.