Prosody HTTP server

Prosody contains a mini built-in HTTP server, which is used for BOSH and other modules.

The following HTTP modules are supplied with Prosody:

mod_http will generally also be auto-loaded by most HTTP modules even if it isn’t specified in the config file. To explicitly enable HTTP, simply load mod_http by adding it to your config:

    modules_enabled = {
        ...
        "http";
        ...
    }

Port configuration

mod_http adds two services, ‘http’ and ‘https’. HTTP plugins are accessible via both services.

They use the standard port configuration. The defaults are:

    http_ports = { 5280 }
    http_interfaces = { "*", "::" }
 
    https_ports = { 5281 }
    https_interfaces = { "*", "::" }

So by default, http://yourprosody.example:5280/ and https://yourprosody.example:5281/ will be the base URLs used by HTTP plugins.

HTTPS Certificate

In Prosody 0.11.x and earlier versions, only a single certificate is supported for HTTPS. If you need support for multiple HTTPS domains, you can should either include all the domains in the same certificate, or use a reverse proxy such as nginx in front of Prosody to handle your HTTPS.

Without a certificate configured, you will see an error like this:

Error binding encrypted port for https: No certificate present in SSL/TLS configuration for https port 5281

To fix it, specify a https_ssl option in the global section to specify a certificate manually. In Prosody 0.10 or later you can also use the automatic location method by specifying a path or creating a symlink.

Prosody 0.9 and before

In 0.9, or if automatic location fails to find a suitable certificate, HTTPS uses the global certificate used in the config file by default. If you wish to use a different certificate, or change options, you can specify this with https_ssl in the global section of your config file:

    https_ssl = {
        certificate = "/path/to/http.crt";
        key = "/path/to/http.key";
    }

Prosody’s HTTPS server does not currently support SNI1, which means only one certificate can be specified. If you need to serve multiple HTTPS hosts with different certificates, you will need to set up a suitable reverse proxy in front of Prosody (e.g. nginx, apache, haproxy or one of the many alternatives).

Prosody 0.10 and later

In Prosody 0.10 the HTTPS service supports automatic certificate detection via service certificates, as well as the https_certificate option.

https_certificate = "certs/example.net.crt"
-- key expected to be found in certs/example.net.key

Virtual hosts

Hosts defined in your config file automatically double as HTTP hosts when mod_http is loaded onto them (if you add mod_http to your global modules_enabled, it will automatically be loaded on every VirtualHost).

To handle HTTP requests to hosts that are not in your Prosody config, you have some options:

Setting a HTTP Host

To map a HTTP Host name to a specific VirtualHost:

    VirtualHost "example.com"
    http_host = "www.example.com"

⚠️ Note that if you may experience unexpected behaviour if multiple VirtualHost entries have the same http_host. See e.g. #1192.

Setting a default host

In the global section of your config, specify:

    http_default_host = "example.com"

Any request for an unknown virtual host will be forwarded to the HTTP modules on example.com. If the intended VirtualHost has http_host set, then http_default_host must be set to the same value.

Path variables

Paths also support a $host variable, allowing modules on multiple virtual hosts to share a single public hostname.

    http_paths = {
        register_web = "/register-on-$host";
    }
    http_host = "www.example.net"
 
    VirtualHost "example.net" -- http://www.example.net/register-on-example.net
 
    VirtualHost "jabber.example" -- http://www.example.net/register-on-jabber.example

Path configuration

It’s possible to change the path that a module is reached at from its default. This is done via the http_paths config option, which may be set globally or per-host:

    http_paths = {
        bosh = "/http-bind"; -- Serve BOSH at /http-bind
        files = "/"; -- Serve files from the base URL
    }

Running behind a reverse proxy

External URL

Some modules expose their own URL in various ways. This URL is built from the protocol, http_host option and port used. If Prosody sits behind a reverse proxy then this URL won’t be the public one.

You can tell prosody about this by setting the http_external_url option, like this:

    http_external_url = "http://www.example.com/"

Trusted reverse proxies

When a reverse proxy is used Prosody will not see the client’s IP, only the proxy’s IP. Reverse proxies usually have ways to forward the real client IP, commonly via a X-Forwarded-For HTTP header. Prosody understands this header but needs to know the IP of the proxy, which is done via the trusted_proxies setting:

trusted_proxies = { "127.0.0.1", "::1", "192.168.1.1", }

Starting with trunk, Prosody also supports CIDR notation (e.g. 192.168.1.0/24), allowing proxies within a specific IP range to be trusted. It also supports the X-Forwarded-Proto header, and will consider the request secure if it has the valuehttps and comes from a trusted proxy. This removes the need for consider_bosh_secure and similar settings.

Incorrect configuration of the trusted_proxies setting, or the proxy itself, may lead to security issues - e.g. allowing clients to spoof their IP address and bypass rate limits or IP-based access controls.

Example web server configuration

These examples show how to forward a whole domain to Prosody. It’s generally possible to forward only individual services by adjusting the path, see examples for BOSH and WebSockets.

Apache

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

a2enmod proxy
a2enmod proxy_http

This example assumes your VirutalHost is named “example.com” and you did not change the default http port. Then in the Apache config file for your domain, add the following lines:

RequestHeader set Host "example.com" #set to your prosody http_host, only necessary if it is different from the Apache2 ServerName.
ProxyPreserveHost On
ProxyPass / "http://127.0.0.1:5280/"
ProxyPassReverse / "http://127.0.0.1:5280/"

Nginx

location / {
    proxy_pass  http://localhost:5280;
    proxy_set_header Host "example.com";
    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 )
  )
)

Adding HTTP-only hosts

You can also make a HTTP-only host via a dummy component:

    Component "www.example.com" "http"
        modules_enabled = { "bosh" }

HTTP modules such as mod_bosh must be loaded explicitly here as global modules are not loaded onto components by default.

  1. This has been implemented in the upcoming version↩︎