Configuring Nginx as a WebSocket Reverse Proxy for noVNC

What is Nginx

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

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, bidirectional communication between client and server, forming part of HTML5 and simplifying the development of interactive web applications.

WebSocket is TCP‑based and enables full‑duplex communication, allowing the server to push data to the client without a request.

During the handshake, the browser sends a WebSocket connection request and the server replies, establishing a fast data channel that offers small headers (about 2 bytes) and server‑push capabilities.

What is noVNC

noVNC lets users access a VNC server from a web page using an HTML5 Canvas; it requires converting TCP VNC traffic to WebSocket so the browser can display the remote desktop.

WebSocket Proxy

To upgrade an HTTP/1.1 connection to WebSocket, the "Upgrade" header is used. However, this header is hop‑by‑hop and does not automatically pass through proxy servers, requiring explicit handling in reverse‑proxy configurations.

Since Nginx 1.3.13, if the upstream returns a 101 (Switching Protocols) response, Nginx creates a tunnel using the client’s "Upgrade" header.

Headers such as "Upgrade" and "Connection" must be explicitly forwarded to the proxy.

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

    server {
        listen 80; # modify listening port as needed
        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 idle connections after 60 seconds; this timeout can be increased with proxy_read_timeout or by sending periodic WebSocket ping frames.

Example – Proxying noVNC

Test 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: vnc-server and client cannot talk directly; proxy-server will reverse‑proxy the noVNC service so client can reach vnc-server through it.

Configuration on proxy-server

Disable the firewall:

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 /etc/nginx/nginx.conf and add the following inside the http block:

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

server {
    listen 8080; # change listening port as needed
    server_name _;
    location / {
        proxy_pass http://192.168.204.10:6080/; # target noVNC WebSocket endpoint
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

Restart Nginx:

systemctl restart nginx

Testing on client

Configure the Windows network adapter (as shown in the original screenshots) and open Firefox to visit:

http://192.168.50.128:8080/vnc.html

The page loads via Nginx, which successfully proxies the WebSocket connection to the remote noVNC service, allowing interactive remote desktop access.