mod_http_altconnect

Overview

Web clients are unable to make conventional TCP connections to Prosody, so they use alternative methods such as BOSH (mod_bosh) and WebSockets (mod_websocket) which can be used from web browsers.

To discover whether a domain supports BOSH and/or WebSockets, and what URLs they can be found at, most web clients fetch a special “host-meta” file which contains this information.

mod_http_altconnect automatically generates this file and serves it via Prosody’s built-in HTTP server.

Correct deployment

For this discovery mechanism to work, the file MUST be served at a very specific location. If your VirtualHost in Prosody is ‘example.com’, the file needs to be located at:

https://example.com/.well-known/host-meta

The domain must match the domain part of your users’ XMPP addresses, which is also the domain specified as the VirtualHost in Prosody’s configuration file.

It must be served on the standard HTTP port (443), even if the BOSH and WebSocket URLs are not. Prosody’s default HTTPS service is on port 5281, which is not sufficient for auto-discovery to work.

prosodyctl shell module info http_altconnect

Configuration

The module works out of the box with no configuration necessary. You just need to make sure the file is served at the correct location, as described above.

This module is automatically loaded by mod_bosh and mod_websocket, as long as you have not disabled it, so you don’t need to add it to modules_enabled.

If, for some reason, you don’t want the module to advertise the BOSH or WebSocket URLs, you can disable them with the advertise_bosh and advertise_websocket options. For example, to hide the BOSH URL:

advertise_bosh = false

modules_disabled = {
    "http_altconnect";
}