WebSockets¶

• Table of contents
• WebSockets
  • Overview
  • Basic Configuration
    • • websockets via mod_wstunnel
      • websockets via mod_proxy
      • websockets via mod_cgi
      • websockets via mod_scgi
      • websockets via mod_fastcgi

WebSocket echo samples

Overview¶

What are websockets? The WebSocket API

lighttpd can facilitate WebSocket connections in numerous ways, including via mod_proxy, mod_cgi, mod_scgi, mod_fastcgi, mod_wstunnel.

• lighttpd supports HTTP/1.1 `Upgrade: websocket` from the HTTP/1.1 connection.
• lighttpd supports HTTP/2 extended CONNECT with `:protocol: websocket` on HTTP/2 streams over a single HTTP/2 connection.

For security reasons and supporting the principle of least surprise, lighttpd support for websockets is intentionally disabled by default. lighttpd dynamic modules may be configured to enable connection upgrade to the websocket protocol.

Since lighttpd 1.4.46, lighttpd mod_cgi, mod_proxy, and mod_wstunnel support websockets. Support in additional dynamic modules mod_scgi and mod_fastcgi has been added in lighttpd 1.4.74.

This document demonstrates multiple ways to configure lighttpd modules to run WebSocket "echo" sample applications.

Basic Configuration¶

websockets via mod_wstunnel¶

Configure mod_wstunnel
mod_wstunnel is a WebSocket tunnel endpoint, terminating the websocket tunnel from a client. mod_wstunnel decodes websocket frames and then passes data (without websocket frames) to a backend, and in the opposite direction encodes responses from backend into websocket frames before sending responses to client.

websockets via mod_proxy¶

Configure mod_proxy and enable proxy.header += ("upgrade" => "enable")
With lighttpd 1.4.74 and later, "upgrade" => "enable" is also a host option in proxy.server
mod_proxy can act as a reverse proxy for websocket connections when upgrade is enabled.

websockets via mod_cgi¶

Configure mod_cgi and enable cgi.upgrade = "enable"
mod_cgi allows the target program to upgrade to use the websocket protocol.

websockets via mod_scgi¶

Configure mod_scgi and add "upgrade" => "enable" to options for each host in scgi.server (lighttpd 1.4.74 and later)
mod_scgi allows the target program to upgrade to use the websocket protocol.

websockets via mod_fastcgi¶

Configure mod_fastcgi and add "upgrade" => "enable" to options for each host in fastcgi.server (lighttpd 1.4.74 and later)
mod_fastcgi allows the target program to upgrade to use the websocket protocol.
While lighttpd does not currently multiplex multiple requests on a single FastCGI connection, the FastCGI protocol allows such. lighttpd mod_fastcgi sends and receives FastCGI packets from the backend, even after a request is upgraded to use the websocket protocol. websocket frames are again framed into FastCGI packets. As such, this may be less efficient than using other lighttpd modules which support upgrading to the websocket protocol.