The "websocket" Module (v3)

Description

This module allows WebSocket clients to connect to the IRC server.

Configuration

To load this module use the following <module> tag:

<module name="websocket">

<bind>

This module extends the core <bind> tags with the following hook types:

Name	Description
websocket	Listens for WebSocket connections.

Example Usage

Listens for plaintext WebSocket connections on the 0.0.0.0:8080 endpoint:

<bind address="0.0.0.0"
      port="8080"
      ...
      hook="websocket">

<websocket>

The <websocket> tag defines settings about how the websocket module should behave. This tag can only be defined once.

Name	Type	Default Value	Description
defaultmode	Text	text	New in v3.12.0! The default action to take when the user does not send a recognised WebSocket subprotocol.
proxyranges	Text	None	New in v3.5.0! A space-delimited list of glob or CIDR matches to trust the X-Real-IP or X-Forwarded-For headers from.
sendastext	Text	Yes	Deprecated in v3.12.0! Whether to send messages to WebSocket clients using text frames instead of binary frames. This requires all text to be transcoded to UTF-8.

The defaultmode field should be set to one of the following values:

Value	Description
binary	Send binary WebSocket frames to clients.
reject	Reject connections that do not explicitly request a subprotocol.
text	Send text WebSocket frames to clients. This requires all text to be transcoded to UTF-8.

Example Usage

<websocket proxyranges="192.0.2.0/24 198.51.100.*"
           defaultmode="text">

<wsorigin>

The <wsorigin> tag defines an WebSocket origin that is allowed to connect to the server. This tag can be defined as many times as required.

Name	Type	Default Value	Description
allow	Text	None	Required! A glob pattern for an URL of a web page that is allowed to connect.

Example Usage

Allows access to the server from all subdomains of example.com:

<wsorigin allow="https://*.example.com">

Special Notes

The following HTTP errors are sent by this module:

Error	Reason
400 Bad Request	Your WebSocket implementation has not sent the Origin header.
400 Bad Request	<websocket:proxyranges> was non-empty and no well-formed X-Real-IP or X-Forwarded-For header was sent.
400 Bad Request	<websocket:defaultmode> was set to reject and no recognised WebSocket subprotocol was sent.
403 Forbidden	You are attempting to connect from a non-whitelisted origin.
501 Not Implemented	Your WebSocket implementation has not sent the Sec-WebSocket-Key header.
503 Service Unavailable	You do not have the sha1 module loaded.

If you add an encrypted WebSocket listener you should create a custom TLS (SSL) profile that has requestclientcert="no" set. This is required to allow connections to your server using Google Chrome.

Some reverse proxy providers (e.g. Cloudflare) drop idle WebSocket connections which can cause problems with this module. It is recommended that you avoid these providers.