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 (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.


Prosody 0.9+

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.

Prosody 0.8

You need to tell Prosody where to run the BOSH listener. The simplest way is to add to the global section in your config file (that is, before any host/component entries) the line:

 bosh_ports = { 5280 }

where 5280 is the port you want BOSH running on. It will be accessible at the default path of /http-bind/.

Alternatively you can specify just a path:

 bosh_ports = { "http-bind" }

and the default port (5280) will be used, along with this path.

For more advanced configuration, the full syntax can be used:

 bosh_ports = {
                    port = 1234;
                    path = "http-bind";
                    interface = "";

Multiple listeners can be started with a comma-separated list of servers:

 bosh_ports = {
                    port = 5280;
                    path = "http-bind";
                    port = 5281;
                    path = "http-bind";
                    ssl = {
                             key = "bosh.key";
                             certificate = "bosh.crt"; 

The above sets up a normal BOSH listener and also a HTTPS (encrypted) BOSH listener on port 5281 using the specified SSL certificate.

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 can connect to a BOSH server at but not to and not

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 to 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:


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

  sudo a2enmod rewrite proxy proxy_http

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

   <Location /http-bind>
      Order allow,deny
      Allow from all
   RewriteEngine On
   RewriteRule ^/http-bind$ [P,L]

Note: If your XMPP server is on the same machine as your web server, replace the target domain above (e.g. with localhost - this is more efficient as connections will use the system's loopback interface and not perform any DNS lookups.

Reload Apache.

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


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_buffering off;
            tcp_nodelay on;


For Lighttpd, proxy configuration looks something like this:

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


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:

doc/setting_up_bosh.txt · Last modified: 2016/02/13 14:39 by Kim Alvefur