Module: mod_wstunnel

(since lighttpd 1.4.46)

WebSocket tunnel endpoint. This module terminates the websocket tunnel from a client. This module then passes data (without websocket frames) to a backend and encodes responses from backend in websocket frames before sending responses to client.

Note: if looking to send websockets to a backend, then see WebSockets for examples using mod_proxy, mod_cgi, mod_scgi, and mod_fastcgi.


Brief description of mod_wstunnel directives

option description
wstunnel.server backend server definition(s) for hosts to which to send requests; options for each backend host
wstunnel.balance load-balancing algorithm for backends ("fair", "least-connection", "round-robin", "hash", or "sticky")
wstunnel.debug debug level (value between 0 and 65535)
wstunnel.frame-type websocket frame type: "text" or "binary" map multiple extensions to the same backend list of permitted origins in Origin request header (optional) send websocket PING frame at given interval in sec (default 0; none sent)

Details for wstunnel.server parameters can be found in mod_fastcgi documentation, since the wstunnel module shares the same code infrastructure with the FastCGI module, and fastcgi.server parameters are very similar.

Example: websocket tunnel to VNC server via noVNC client

Follow instructions to download and install, or use available packages for your Linux/*BSD distribution.

If noVNC files are installed in /usr/share/novnc, and x11vnc is running as VNC server with x11vnc -localhost -forever -display :0 then lighttpd mod_wstunnel can be configured with:

server.document-root = "/usr/share/novnc" 
server.indexfiles = ("index.html")
server.modules += ( "mod_wstunnel" )
$HTTP["url"] =~ "^/websockify" {
    wstunnel.server = ( "" => ( ( "host" => "", "port" => "5900" ) ) )
    wstunnel.frame-type = "binary" 

Please take proper precautions to limit access to the VNC server, possibly including requiring proper authentication and limiting access to certain source IPs.

Example: websocket tunnel to a trivial "echo" script which reads and echoes line-by-line

WebSockets: Sample:

Updated by gstrauss 6 months ago · 17 revisions