WebSocket proxying in Nginx - Step-by-Step Execution

Process Flow - WebSocket proxying

Client sends WebSocket request

↓

Nginx receives request

↓

Check if request is WebSocket upgrade

↓

Set proxy headers

↓

Proxy to backend WebSocket server

↓

Backend responds and upgrades

↓

Nginx tunnels data between client and backend

↓

Connection open

Nginx checks if the incoming request wants to upgrade to WebSocket, sets special headers, then proxies the connection to the backend WebSocket server, allowing data to flow between client and server.

Execution Sample

Nginx

location /ws/ {
    proxy_pass http://backend_ws;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
}

This config proxies WebSocket requests at /ws/ to the backend server, setting headers needed for WebSocket upgrade.

Process Table

Step	Action	Request Header Upgrade	Connection Header	Proxy Headers Set	Proxy Pass Target	Result
1	Client sends request to /ws/	websocket	Upgrade	Not set yet	Not set yet	Request received by Nginx
2	Nginx checks Upgrade header	websocket	Upgrade	Not set yet	Not set yet	Upgrade detected, proceed with WebSocket proxying
3	Set proxy headers	websocket	Upgrade	Upgrade=$http_upgrade, Connection=Upgrade	Not set yet	Headers prepared for proxying
4	Proxy pass to backend_ws	websocket	Upgrade	Upgrade=websocket, Connection=Upgrade	http://backend_ws	Request forwarded to backend
5	Backend responds with 101 Switching Protocols	websocket	Upgrade	Upgrade=websocket, Connection=Upgrade	http://backend_ws	Connection upgraded to WebSocket
6	Nginx tunnels data	websocket	Upgrade	Upgrade=websocket, Connection=Upgrade	http://backend_ws	Bidirectional data flow established
7	Connection open	websocket	Upgrade	Upgrade=websocket, Connection=Upgrade	http://backend_ws	WebSocket connection active

💡 WebSocket connection established and data tunneled until closed

Status Tracker

Variable	Start	After Step 3	After Step 4	Final
$http_upgrade	websocket	websocket	websocket	websocket
proxy_set_header Upgrade	unset	websocket	websocket	websocket
proxy_set_header Connection	unset	Upgrade	Upgrade	Upgrade
proxy_pass	unset	unset	http://backend_ws	http://backend_ws

Key Moments - 3 Insights

Why do we need to set 'proxy_http_version 1.1;' for WebSocket proxying?

Because WebSocket requires HTTP/1.1 to support the Upgrade header. Without setting this, Nginx defaults to HTTP/1.0 which does not support connection upgrades. See execution_table step 3 where headers are set after specifying HTTP version.

What happens if we forget to set 'proxy_set_header Connection "upgrade";'?

The backend server will not recognize the request as a WebSocket upgrade request, so it won't switch protocols. This breaks the WebSocket handshake. Refer to execution_table step 3 where setting this header is crucial.

Why does Nginx tunnel data after the upgrade instead of buffering it?

Because WebSocket is a full-duplex connection needing real-time data flow. Nginx acts as a transparent tunnel after upgrade, forwarding data both ways without buffering. See execution_table steps 6 and 7.

Visual Quiz - 3 Questions

Look at the execution table, at which step does Nginx detect the WebSocket upgrade request?

A Step 2

B Step 4

C Step 1

D Step 5

💡 Hint

Check the 'Action' and 'Result' columns in execution_table rows to see when upgrade is detected.

According to variable_tracker, what is the value of 'proxy_set_header Connection' after step 3?

A unset

B Upgrade

C upgrade

D websocket

💡 Hint

Look at the 'proxy_set_header Connection' row in variable_tracker after step 3.

If 'proxy_http_version 1.1;' was omitted, what would likely happen?

A Nginx would use HTTP/2 automatically

B Connection would still upgrade successfully

C WebSocket upgrade would fail

D Backend server would reject all requests

💡 Hint

Refer to key_moments about why HTTP/1.1 is required for upgrade headers.

Concept Snapshot

WebSocket proxying in Nginx:
- Use 'proxy_http_version 1.1;' to enable HTTP/1.1
- Set 'proxy_set_header Upgrade $http_upgrade;' to forward upgrade header
- Set 'proxy_set_header Connection "Upgrade";' to allow protocol switch
- Use 'proxy_pass' to backend WebSocket server
- Nginx tunnels data after 101 Switching Protocols response
- Ensures real-time bidirectional WebSocket communication

Full Transcript

When a client sends a WebSocket request, Nginx first checks if the request includes the Upgrade header indicating a WebSocket handshake. If yes, Nginx sets the HTTP version to 1.1 and sets proxy headers 'Upgrade' and 'Connection' to allow the protocol upgrade. Then it proxies the request to the backend WebSocket server. When the backend responds with a 101 Switching Protocols status, Nginx starts tunneling data between client and backend, enabling full-duplex WebSocket communication. This process continues until the connection closes.