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

To enable HTTP, simply load mod_http by adding it to your config:

    modules_enabled = {

mod_http will generally also be auto-loaded by most HTTP modules even if it isn't specified in the config file.

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

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

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 ""
    http_host = ""

Setting a default host

In the global section of your config, specify:

    http_default_host = ""

Any request for an unknown virtual host will be forwarded to the HTTP modules on 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 = ""
    VirtualHost "" --
    VirtualHost "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 = ""

Adding HTTP-only hosts

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

    Component "" "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: 2016/10/05 21:56 by Kim Alvefur