How to Proxy WebSocket with Nginx: Configurations, TLS, and Keep‑Alive Tips

Hello, I am Xiao Jiang. In the previous article we introduced the WebSocket protocol; this article reviews it and explains how to use Nginx to proxy WebSocket connections.

WebSocket is an HTML5 protocol that enables full‑duplex communication between browsers and servers, saving resources and bandwidth. Like HTTP it uses an established TCP connection, but unlike HTTP it upgrades the connection via the HTTP Upgrade header and then operates independently of HTTP.

WebSocket is a bidirectional communication protocol; after the connection is established, both server and client can actively send or receive data, similar to a raw socket. WebSocket requires an initial handshake similar to TCP before communication can begin.

In production environments where multiple WebSocket servers need high performance and high availability, a load‑balancing layer is required. Nginx has supported WebSocket since version 1.3 and can act as a reverse proxy and load balancer for WebSocket services.

To enable WebSocket proxying, the Upgrade and Connection headers must be correctly set. Below are the essential configuration steps.

Nginx configuration for WebSocket proxy

1. Add a map directive in the http block

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

2. Configure the virtual host (location block)

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "$connection_upgrade";
# Alternatively, you can hard‑code "Upgrade" for the Connection header

3. Complete example (including TLS settings and upstream definition)

upstream sre_backend {
    hash $remote_addr consistent;
    server sre1.ayunw.cn:8080;
    server sre2.ayunw.cn:8080;
    server sre3.ayunw.cn:8080;
}

server {
    listen 443 ssl;
    server_name sre.ayunw.cn;

    ssl_certificate /data/certs/nginx/sre.ayunw.cn.crt;
    ssl_certificate_key /data/certs/nginx/sre.ayunw.cn.key;
    ssl_session_timeout 5m;
    ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    location / {
        proxy_pass http://sre_backend;
        proxy_ssl_server_name on;
        include proxy.conf;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "$connection_upgrade";
    }

    error_page 500 502 503 504 /50x.html;
    location = /50x.html { root html; }
}

By default, Nginx closes a proxy connection after 60 seconds of inactivity. You can increase this timeout with proxy_read_timeout and proxy_send_timeout directives.

Timeout configuration example

http {
    server {
        location / {
            proxy_pass http://sre_backend;
            proxy_http_version 1.1;
            proxy_connect_timeout 5s;
            proxy_read_timeout 60s;   # adjust as needed, e.g., 300s for 5‑minute idle period
            proxy_send_timeout 30s;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "$connection_upgrade";
        }
    }
}

proxy_read_timeout

defines how long Nginx waits for a response from the upstream server between two read operations; increasing it prevents premature disconnection of idle WebSocket connections. proxy_send_timeout controls the timeout for sending data to the upstream server.

WebSocket vs. HTTP

Both are TCP‑based, reliable transport protocols and operate at the application layer. WebSocket provides full‑duplex communication, while HTTP is request‑response (single‑direction). WebSocket requires an initial HTTP handshake (Upgrade and Connection headers) before establishing a persistent TCP channel.

During the handshake, data is transferred over HTTP, but once the connection is established, WebSocket communication no longer depends on HTTP.

In summary, Nginx can proxy WebSocket traffic by upgrading HTTP connections, configuring appropriate headers, and adjusting timeout settings to keep long‑living connections stable.