Setting up a BOSH server

BOSH (previously known as ‘HTTP binding’ or “http-bind”) is a technology to use XMPP over HTTP, the protocol that powers the web. This allows XMPP applications to run in web pages, but also any other HTTP-only environment such as behind restrictive firewalls.

This page acts as a guide to setting up Prosody as a BOSH server for the first time. For information on all BOSH configuration options, see the mod_bosh module page.

Note: An alternative solution to that described here is to set up an external BOSH connection manager, which acts as a proxy between BOSH clients and normal XMPP to Prosody (and also to any other server). For a list of these, see the list of BOSH connection managers on xmpp.org (all should be compatible with Prosody).

Enabling the module

Firstly load the ‘bosh’ module, or add it to your modules_enabled line in your config file.

Configuring

By default you will find BOSH accessible at these URLs:

For further configuration on the Prosody side, such as changing ports and SSL certificates, see Prosody HTTP server. Otherwise skip down to Cross-domain issues to set up your public web server if necessary.

Cross-domain issues

If your BOSH app is running inside a web browser you will find that browsers are typically very restrictive in where they let Javascript apps connect to. In particular they hold a “same-origin” policy, and prevent apps from connecting to any domain/port other than the one they were served from.

This means that http://example.com/app.js can connect to a BOSH server at http://example.com/http-bind but not to http://other.example.com/http-bind and not http://example.com:5280/http-bind.

There are two ways to overcome this:

Cross-domain requests (CORS)

There is a relatively new HTTP extension that allows web servers to tell browsers that cross-domain requests are ok and permitted, called CORS.

Prosody supports CORS, but if before you choose to rely on it you should check if it is supported by the browsers your users will be using - some older browsers might not support it. Check this compatibility table for browser CORS support.

CORS is disabled by default in Prosody to protect private servers from being accessed scripts hosted on third-party websites. If you want to enable support however, simply add to your config in the global section:

    cross_domain_bosh = true

Proxying requests

The traditional solution to solving the same-origin problem is to have the web server that serves the app script also act as a proxy to the real BOSH server at some URL. For example you would configure your web server to forward requests for https://example.com/http-bind to http://example.com:5280/http-bind. This requires more server resources, but is guaranteed to work across all browsers.

Note: If your web server does https and you proxy to Prosodys http port, it will think that connections are insecure and may not offer some features.

To remedy this you can add:

-- In the global section
consider_bosh_secure = true

How to do proxy a URL depends on your web server:

Apache

See mod_proxy. Firstly, ensure you have the correct modules enabled in Apache:

a2enmod proxy
a2enmod proxy_http

Then in the Apache config file for your domain, add the following lines:

<Location /http-bind>
ProxyPass "http://localhost:5280/http-bind"
ProxyPassReverse / "http://localhost:5280/http-bind"
</Location>

Note: If your XMPP server is not on the same machine as your web server, replace the target domain above (i.e. localhost).

Reload Apache.

Test by visiting the URL in your browser: http://example.com/http-bind - you should see a message from Prosody, and not any Apache errors.

nginx

If you are using nginx, try the following in your nginx config:

location /http-bind {
    proxy_pass  http://localhost:5280/http-bind;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    tcp_nodelay on;
}

Lighttpd

For Lighttpd, proxy configuration looks something like this:

server.modules += ( "mod_proxy" )
proxy.server = (
  "/http-bind" => (
    ( "host" => "127.0.0.1", "port" => 5280 )
  )
)

ASP.NET/IIS

IIS can be configured as a reverse proxy. If access to IIS configuration is not available, an ASP.NET application can itself act as a proxy. A detailed write-up is available here: Setup of Prosody with ASP.NET/IIS on a Shared Hosting with a web based XMPP Client.

Tested clients

These clients and libraries support BOSH and have been tested against Prosody: