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_bosh
  • mod_websocket (in 0.10+)
  • mod_http_files

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

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

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:

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

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.

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", }

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↩︎