How to handle WebSocket connections with mod_proxy_wstunnel?
Jul 05, 2025 am 12:47 AMThe mod_proxy_wstunnel module is the key to Apache's handling of WebSocket connections, which ensures that requests are correctly forwarded to the backend and the connection is constantly opened. 1. First enable the mod_proxy and mod_proxy_wstunnel modules, and restart the Apache service; 2. Use the ws:// or wss:// protocol when configuring VirtualHost to ensure path matching; 3. Add the RequestHeader to set Upgrade and Connection headers to support protocol switching; 4. Configure a valid certificate and point to the wss:// address when using SSL/TLS; 5. Test the connection through the browser console, wscat and other tools, and check the Apache log troubleshooting problem. As long as the protocol upgrade and path mapping are configured correctly, WebSocket can run stably.
When handling WebSocket connections, if you use Apache as the reverse proxy server, the mod_proxy_wstunnel module is the key component you need. It allows you to correctly forward WebSocket requests to the backend application server without interrupting the connection or downgrading to long polling.
Below are some key points and configuration suggestions that need to be paid attention to in actual operation.
Enable the necessary modules
Before starting configuration, make sure your Apache has the following modules enabled:
-
mod_proxy
-
mod_proxy_wstunnel
You can enable these modules by running the following command (taking the Ubuntu/Debian system as an example):
sudo a2enmod proxy sudo a2enmod proxy_wstunnel
Restart Apache after enabled:
sudo systemctl restart apache2
Configure reverse proxy support for WebSocket
To get WebSocket to work properly, you need to pay special attention to the request header and protocol upgrade section. A basic configuration example is as follows:
<VirtualHost *:80> ProxyPreserveHost On ProxyPass /ws/ ws://backend-server/ ProxyPassReverse /ws/ http://backend-server/ # If it is HTTPS, use wss:// and the corresponding ProxyPass setting</VirtualHost>
Here are a few key points to note:
- Use a URL starting with
ws://
orwss://
to specify the destination address. - Make sure that the path matches correctly, such as the front-end access
/ws/xxx
, and the back-end must be able to handle the corresponding paths. - If you have both HTTP and WebSocket interfaces, you can map the WebSocket path separately to avoid interfering with other services.
Handle FAQs
Request denied or connection interrupted
This is usually caused by not properly setting the Upgrade and Connection request headers. You can add the following content to the configuration to force the delivery of these headers:
RequestHeader set Upgrade "websocket" env=HTTP_UPGRADE RequestHeader set Connection "upgrade" env=HTTP_CONNECTION
This way Apache will correctly forward the WebSocket protocol switching request to the backend.
Pay attention to configuration when using SSL/TLS
If you are using HTTPS and WSS (WebSocket Secure), you need to make sure that the SSL is configured correctly and that Apache's ProxyPass points to wss://
address. Additionally, the SSL certificate must be valid, otherwise the browser may be disconnected directly.
Testing and debugging methods
The easiest way to test whether WebSocket works properly is to initiate a connection using a browser console or some WebSocket client tool such as wscat or Postman.
In addition, Apache's log files (usually in /var/log/apache2/access.log
and /var/log/apache2/error.log
) can help troubleshoot the cause of connection failure.
Basically that's it. WebSocket is prone to problems in reverse proxy environments mainly focuses on protocol upgrades and path mapping. As long as these two points are configured properly, the rest will be left to the backend to handle.
The above is the detailed content of How to handle WebSocket connections with mod_proxy_wstunnel?. For more information, please follow other related articles on the PHP Chinese website!

Hot AI Tools

Undress AI Tool
Undress images for free

Undresser.AI Undress
AI-powered app for creating realistic nude photos

AI Clothes Remover
Online AI tool for removing clothes from photos.

Clothoff.io
AI clothes remover

Video Face Swap
Swap faces in any video effortlessly with our completely free AI face swap tool!

Hot Article

Hot Tools

Notepad++7.3.1
Easy-to-use and free code editor

SublimeText3 Chinese version
Chinese version, very easy to use

Zend Studio 13.0.1
Powerful PHP integrated development environment

Dreamweaver CS6
Visual web development tools

SublimeText3 Mac version
God-level code editing software (SublimeText3)

Hot Topics

When encountering a "ConnectionRefused" error, the most direct meaning is that the target host or service you are trying to connect to explicitly reject your request. 1. Check whether the target service is running, log in to the target machine to check the service status using systemctlstatus or psaux, and start manually if it is not started; 2. Confirm whether the port is listening correctly, use netstat or ss command to check whether the service is listening to the correct port, modify the configuration file if necessary and restart the service; 3. Firewall and security group settings may cause connection denied, check the local firewall rules and cloud platform security group configuration, and temporarily close the firewall during testing; 4. IP address or DNS resolution errors may also cause problems, use ping or

Enabling KeepAlive can significantly improve website performance, especially for pages that load multiple resources. It reduces connection overhead and speeds up page loading by keeping the browser and server connection open. If the site uses a large number of small files, has duplicate visitors, or attaches importance to performance optimization, KeepAlive should be enabled. When configuring, you need to pay attention to setting a reasonable timeout time and number of requests, and test and verify its effect. Different servers such as Apache, Nginx, etc. all have corresponding configuration methods, and you need to pay attention to compatibility issues in HTTP/2 environments.

ToenableOCSPstaplinginApache,ensureyoumeettheprerequisitesandconfigurethenecessarydirectives.First,confirmyouareusingApache2.4.1ornewerwithmod_sslenabled,OpenSSL0.9.8hornewer,andhaveavalidSSLcertificateinstalled.Next,edityourApacheSSLvirtualhostconfi

The mod_proxy_wstunnel module is the key to Apache's handling of WebSocket connections, which ensures that requests are correctly forwarded to the backend and the connection is constantly opened. 1. First enable the mod_proxy and mod_proxy_wstunnel modules, and restart the Apache service; 2. Use the ws:// or wss:// protocol when configuring VirtualHost to ensure path matching; 3. Add the RequestHeader to set Upgrade and Connection headers to support protocol switching; 4. Configure valid certificates and point to the wss:// address when using SSL/TLS; 5. Test through browser console, wscat and other tools

To improve Apache performance, optimize configuration parameters are required. 1. Adjust KeepAlive parameters: Enable MaxKeepAliveRequests and set to 500 or higher, and set KeepAliveTimeout to 2~3 seconds to reduce connection overhead. 2. Configure the MPM module: Set StartServers, MinSpareServers, MaxSpareServers and MaxClients in prefork mode; set ThreadsPerChild and MaxRequestWorkers in event or worker mode to avoid excessive load. 3. Control memory usage: based on the memory usage of a single process

Apache's default web root directory is /var/www/html in most Linux distributions. This is because the Apache server provides files from a specific document root directory. If the configuration is not customized, systems such as Ubuntu, CentOS, and Fedora use /var/www/html, while macOS (using Homebrew) is usually /usr/local/var/www, and Windows (XAMPP) is C:\xampp\htdocs; to confirm the current path, you can check the Apache configuration file such as httpd.conf or apache2.conf, or create a P with phpinfo()

To improve Apache security, we need to start from module management, permission control, SSL encryption, log monitoring, etc. 1. Close unnecessary modules such as mod_imap, mod_info, etc., and make use of the LoadModule line and restart the service to take effect; 2. Set the root directory permissions to 755 or below, restrict write permissions, and disable directory traversal and script execution in the configuration; 3. Enable HTTPS, use Let'sEncrypt certificate and disable the old version of the protocol and weak encryption suite; 4. Check the access and error logs regularly, combine fail2ban to block abnormal IP, and use IP restrictions on sensitive paths.

Enable HSTS to force browsers to access websites through HTTPS, improving security. 1. To enable HTTPS in Apache, you must first configure HTTPS, and then add Strict-Transport-Security response header in the site configuration file or .htaccess; 2. To configure max-age (such as 31536000 seconds), includeSubDomains and preload parameters; 3. Make sure that the mod_headers module is enabled, otherwise run sudoa2enmodheaders and restart Apache; 4. You can optionally submit to the HSTSPreload list, but it must satisfy that both the main site and the subdomain support HTTPS.
