Apache 2.4.47+ WebSocket Reverse Proxying: mod_proxy_http, mod_proxy_wstunnel, and HTTP/2 Scope

For Apache HTTP Server 2.4.47 and later, Apache documents WebSocket protocol-upgrade handling through mod_proxy_http. The older mod_proxy_wstunnel module is still documented, but it is marked deprecated for this use. In Apache 2.4.48 and later, its default behavior is to let mod_proxy_http handle the request; setting ProxyWebsocketFallbackToProxyHttp Off restores the older handling behavior.

This is a version-aware configuration boundary, not a guarantee that every WebSocket deployment will work without testing. The supplied documentation does not establish your backend application’s path, authentication behavior, TLS setup, load-balancing design, or compatibility with every third-party module.

What changes at Apache 2.4.47?

Apache’s mod_proxy_wstunnel documentation says that, since Apache HTTP Server 2.4.47, protocol upgrades can be handled by mod_proxy_http in accordance with RFC 7230. The same page describes mod_proxy_wstunnel as deprecated and identifies it as the WebSocket tunneling module.

The practical decision is therefore based first on the Apache version:

The table describes documented module behavior only. It does not establish which modules are loaded on a particular server or whether a backend accepts the requested upgrade.

The Apache 2.4.48 fallback control

ProxyWebsocketFallbackToProxyHttp is available in mod_proxy_wstunnel from Apache 2.4.48. Its documented default is On. With that setting, mod_proxy_wstunnel hands the request to mod_proxy_http. Setting it to Off makes mod_proxy_wstunnel handle WebSocket requests as it did in Apache 2.4.46 and earlier.

That default is a module-specific rule. It should not be read as a universal guarantee for every proxy feature, third-party module, or backend application. The supplied excerpts do not document the results of changing this directive for a particular application.

What the documented ProxyPass scope says

The supplied mod_http2 documentation states that HTTP/2 WebSocket requests can be used with a ProxyPass containing the upgrade=websocket parameter without further changes in that specific HTTP/2 handling path. It also says that the HTTP/2 WebSocket feature is not enabled by default because compatibility with third-party modules may be affected.

This creates an important boundary: the documentation supports the relationship between HTTP/2 WebSocket bootstrapping and a ProxyPass using upgrade=websocket, but it does not prove that any arbitrary third-party WebSocket handler will transfer data correctly over HTTP/2. The page explicitly distinguishes protocol bootstrapping from the additional support needed for data transfer.

A safe version-based decision

If the server is Apache 2.4.47 or newer

Review the mod_proxy_http approach and the documented ProxyPass upgrade parameter. If the server still uses mod_proxy_wstunnel, remember that the module is deprecated for this use. On Apache 2.4.48 and newer, its documented default fallback is to mod_proxy_http.

If the server is Apache 2.4.48 or newer and the older behavior is required

The supplied documentation identifies ProxyWebsocketFallbackToProxyHttp Off as the control that keeps WebSocket handling in mod_proxy_wstunnel. The reason for changing it, the affected virtual host, and the expected rollback should be recorded before making a production change. The excerpts do not establish when an administrator should select this setting for a particular application.

If the server is older than Apache 2.4.47

The supplied mod_proxy_wstunnel page provides the older WebSocket proxying pattern, including ws:// and wss:// targets and examples where WebSocket-specific proxy rules are placed before a general HTTP proxy rule. Because the supplied evidence is excerpted and does not provide a complete compatibility matrix, confirm the exact installed Apache version and consult the matching vendor documentation before changing configuration.

Operational checks before changing configuration

• Confirm the exact Apache HTTP Server version.
• Identify whether the current configuration uses mod_proxy_http, mod_proxy_wstunnel, or both.
• Check whether the intended request path is covered by a specific ProxyPass rule. Apache documents that the first matching rule wins and recommends ordering conflicting rules from the longest URL first.
• For HTTP/2, treat WebSocket bootstrapping and subsequent data transfer as separate compatibility questions.
• Test the change in the affected virtual host with a reversible configuration change and a documented rollback. The supplied excerpts do not define an application-specific test procedure.

Research method and limitations

This article was prepared only from the supplied public Apache documentation excerpts, retrieved on September 21–22, 2026 UTC. The excerpts support the stated version boundaries, directive behavior, ProxyPass upgrade scope, and Apache’s documented rule-ordering guidance. One mod_proxy passage was truncated, and no competing page was successfully fetched. This is a research-based explanation, not a hands-on review, lab test, benchmark, or comprehensive compatibility survey. It does not establish behavior for a particular backend, distribution build, third-party module, or complete production configuration.

Sources

• Apache mod_proxy_wstunnel documentation
• Apache mod_http2 documentation
• Apache mod_proxy documentation