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

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

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

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
    }

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 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/"

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.

 
doc/http.txt · Last modified: 2017/09/29 10:27 by Kim Alvefur