WebSockets

XMPP over WebSockets is a method of providing bi-directional communication, similar to BOSH but with less overhead.

Configuration

WebSocket support is provided by mod_websocket, so uncomment or add "websocket" in your modules_enabled list to enable WebSockets.

With default HTTP settings the WebSocket connection endpoint will be available at the following locations:

ws://example.com:5280/xmpp-websocket
wss://example.com:5281/xmpp-websocket

See documentation on HTTP settings for how to map HTTP Hosts to Prosody VirtualHosts, change the path or ports etc.

HTTP Proxy Passthrough

If you proxy WebSocket connections trough a HTTP proxy or server that handles HTTPS, you can set consider_websocket_secure = true to tell Prosody not to worry about the connections being unencrypted.

If you know how to configure other HTTP servers for WebSockets, let us know.

Nginx

See nginx websocket documentation.

location /xmpp-websocket {
    proxy_pass http://localhost:5280/xmpp-websocket;
    proxy_http_version 1.1;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Upgrade $http_upgrade;

    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 900s;
}

The Host header needs to be forwarded to allow Prosody to find the correct VirtualHost to use.

The X-Forwarded-For header lets Prosody to know the real IP. The IP of nginx must be included in the trusted_proxies config option.

The longer proxy_read_timeout prevents nginx from closing the connection if it remains silent for a while. A value higher than the socket framework network_settings.read_timeout setting is advisable. (default 840 seconds in starting with 0.12.0).

Apache

See mod_proxy_wstunnel and mod_proxy.

<IfModule mod_proxy.c>
    <IfModule mod_proxy_wstunnel.c>
    ProxyTimeout 900
    <Location "/xmpp-websocket">
        ProxyPass "ws://localhost:5280/xmpp-websocket"
    </Location>
    </IfModule>
</IfModule>

The connection is automatically upgraded to a websocket connection.

The ProxyTimeout directive sets a longer timeout (default: 60 seconds).

Assuming your web server listens on https://example.org, use wss://example.org/xmpp-websocket in your client.