WebSocket Options

Crossbar.io is built on an advanced and complete WebSocket implementation that exposes various options and tunables you might be interested in, especially if you take your server to production.

For options related to WebSocket compression, please see here.

To set options on a WebSocket transport, add an options dictionary to the transport configuration part. Here is an example:

   "type": "websocket",
   "endpoint": {
      "type": "tcp",
      "port": 8080
   "url": "ws://localhost:8080",
   "options": {
      "enable_webstatus": false

Above will run a WebSocket transport, but disable the automatic rendering of a server status page when the WebSocket server is accessed from a regular Web client that does not upgrade to WebSocket.

Available Options

The available options are:

option description
allowed_origins A list of allowed WebSocket origins - can use * as a wildcard character, e.g. [“https://*.tavendo.com”, “http://localhost:8080”]
external_port The external visible port this service be reachable under (i.e. when running behind a L2/L3 forwarding device) (default: null)
enable_hybi10 Enable Hybi-10 version of WebSocket (an intermediary spec). (default: true)
enable_rfc6455 Enable RFC6455 version of WebSocket (the final spec). (default: true)
enable_webstatus Enable the WebSocket server’s status rendering page. (default: true)
validate_utf8 Validate incoming WebSocket text messages for UTF8 conformance. (default: true)
mask_server_frames Mask server-sent WebSocket frames. WARNING: Enabling this will break protocol compliance! (default: false)
require_masked_client_frames Require all WebSocket frames received to be masked. (default: true)
apply_mask Actually apply WebSocket masking (both in- and outgoing). (default: true)
max_frame_size Maximum size in bytes of incoming WebSocket frames accepted or 0 to allow any size. (default: 0)
max_message_size Maximum size in bytes of incoming WebSocket messages accepted or 0 to allow any size. (default: 0)
auto_fragment_size Automatically fragment outgoing WebSocket messages into WebSocket frames of payload maximum specified size in bytes or 0 to disable. (default: 0)
fail_by_drop On severe errors (like WebSocket protocol violations), brutally drop the TCP connection instead of performing a full WebSocket closing handshake. (default: false)
echo_close_codereason During a WebSocket closing handshake initiated by a peer, echo the peer’s close code and reason. Otherwise reply with code 1000 and no reason. (default: false)
open_handshake_timeout WebSocket opening handshake timeout in ms or 0 to disable. (default: 0)
close_handshake_timeout WebSocket closing handshake timeout in ms or 0 to disable. (default: 0)
tcp_nodelay Set the TCP No-Delay (“Nagle”) socket option (default: true)
auto_ping_interval Send a WebSocket ping every this many ms or 0 to disable. (default: 0)
auto_ping_timeout Drop the connection if the peer did not respond to a previously sent ping in this many ms or 0 to disable. (default: 0)
auto_ping_size Payload size for pings sent, must be between 4 and 125 (default: 4)
compression enable WebSocket compression - see WebSocket Compression
require_websocket_subprotocol Require WebSocket clients to properly announce the WAMP-WebSocket subprotocols it is able to speak This can be one or more from wamp.2.json, wamp.2.msgpack, wamp.2.json.batched and wamp.2.json.batched. Crossbar.io will by default require the client to announce the subprotocols it supports and select one of the announced subprotocols. If this option is set to false, Crossbar.io will no longer require the client to announce subprotocols and assume wamp.2.json when no WebSocket subprotocol is announced. (default: true)

Production Settings

For example, here is a configuration for a production WebSocket service with conservative settings:

   "type": "websocket",
   "endpoint": {
      "type": "tcp",
      "port": 8080
   "url": "ws://myserver.com:8080",
   "options": {
      "enable_webstatus": false,
      "max_frame_size": 1048576,
      "max_message_size": 1048576,
      "auto_fragment_size": 65536,
      "fail_by_drop": true,
      "open_handshake_timeout": 2500,
      "close_handshake_timeout": 1000,
      "auto_ping_interval": 10000,
      "auto_ping_timeout": 5000,
      "auto_ping_size": 4