How to Proxy WebSocket with Nginx for noVNC: Step‑by‑Step Guide

What is Nginx

Nginx (engine x) is a high‑performance HTTP and reverse‑proxy server that also supports IMAP/POP3/SMTP.

It is a lightweight web server/reverse‑proxy and email proxy released under a BSD‑like license, known for low memory usage and strong concurrency.

What is WebSocket

The WebSocket protocol provides real‑time, full‑duplex communication between client and server, simplifying the development of interactive web applications.

It is a TCP‑based protocol that enables browsers and servers to exchange data instantly.

During the handshake, the browser sends a WebSocket request and the server responds, establishing a fast, bidirectional channel.

Header – the handshake header is tiny, about 2 bytes.

Server Push – the server can push data to the client without waiting for a request.

What is noVNC

noVNC allows access to a VNC server from a web page using HTML5 Canvas; it converts TCP to WebSocket so the browser can display the remote desktop, acting as a web‑based VNC client.

WebSocket Proxy

To upgrade an HTTP/1.1 connection to WebSocket, the protocol‑switching mechanism of HTTP/1.1 is used.

A subtle issue is that the "Upgrade" header is hop‑by‑hop and does not automatically reach proxy servers; forward proxies can use the CONNECT method, but reverse proxies need special handling.

Since version 1.3.13, Nginx can establish a tunnel when the upstream returns a 101 (Switching Protocols) response, using the client’s "Upgrade" header.

Because hop‑by‑hop headers like "Upgrade" and "Connection" are not forwarded, they must be explicitly set in the proxy configuration.

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

    server {
        listen 80; # modify listening port
        server_name _;
        location / {
            proxy_pass  # set to the target WebSocket IP and port
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
        }
    }
}

By default, Nginx closes a connection after 60 seconds of inactivity; this timeout can be increased with the proxy_read_timeout directive or by sending periodic WebSocket ping frames.

Example – Proxy noVNC

Experimental Environment

CentOS 7 VM with noVNC installed (named vnc-server ), IP 192.168.204.10 (NAT).

Minimal CentOS 7 VM (named proxy-server ), IP 192.168.204.133 (NAT) and 192.168.50.128 (host‑only).

Windows 7 VM (named client ), IP 192.168.50.129 (host‑only).

Network isolation between vnc-server and client is bridged by proxy-server , which reverse‑proxies the noVNC service so the client can reach the VNC server through the proxy.

Configuration proxy-server

Disable the firewall on the proxy server:

setenforce 0
systemctl stop firewalld
systemctl disable firewalld

Install Nginx:

yum install -y epel*
yum install -y nginx
systemctl start nginx
systemctl enable nginx

Edit the Nginx configuration file:

vim /etc/nginx/nginx.conf

Add the following to the http block:

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

server {
    listen 8080; # modify listening port
    server_name _;
    location / {
        proxy_pass http://192.168.204.10:6080/; # target WebSocket IP and port
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

Restart Nginx:

systemctl restart nginx

Test on client

Configure the Windows 7 network adapter (see image).

In Firefox, open the proxy server’s host‑only web service: http://192.168.50.128:8080/vnc.html The page shows that Nginx successfully proxies the WebSocket traffic for noVNC.

Link: https://www.cnblogs.com/connect/p/nginx-proxy-websocket.html

(Copyright © original author, all rights reserved.)