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 since 0.12.0 are:

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

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

HTTPS Certificate

Prosody 0.12.x and later will automatically find and serve an appropriate certificate for HTTPS, based on the certificates already used for your XMPP services and the hostname requested by the client or web browser. No additional configuration should be necessary for most deployments.

In Prosody 0.11.x and earlier versions, only a single certificate is supported for HTTPS, and manual configuration is generally necessary. If you need support for multiple HTTPS domains, you 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. Reverse proxying is discussed later on this page.

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.

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

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:

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

    http_default_host = "example.com"

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
    }

The keys in the http_paths config option mirror the module names. For HTTP modules http_ is stripped.

Cross-domain (CORS) support

From version 0.12, Prosody’s HTTP server will automatically add CORS headers to allow web browsers to access Prosody’s URLs from other domains. For versions prior to 0.12, see individual module documentation for details about their CORS configuration.

Without CORS, web browsers apply a default “same-origin policy” which restricts access from other domains (including subdomains). While this security measure is generally necessary for many standard web apps, it is unnecessary for services that Prosody typically exposes, such as BOSH, websockets and file upload/download. That’s because these services have their own authentication mechanisms (not using cookies) or are designed for open access.

Prosody 0.12 supports the following CORS options in the global section of the config:

From Prosody 0.12.1, it is possible to override each module’s default CORS settings via the http_cors_override option in the global section of your config.

For example, to disable CORS for mod_bosh and mod_websocket, you could set the following:

    http_cors_override = {
        bosh = {
            enabled = false;
        };
        websocket = {
            enabled = false;
        };
    }

As well as enabled, you can also set credentials to true/false to indicate whether the Access-Control-Allow-Credentials header should be sent, and you can override allowed headers, methods and origins on a per-app basis this way too.

Running behind a reverse proxy

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

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

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

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

a2enmod proxy proxy_http headers

<VirtualHost *:443>
ServerName www.example.com
    SSLEngine On
    SSLCertificateFile /path/to/certificatefolder/fullchain.pem
    SSLCertificateKeyFile /path/to/certificatefolder/privkey.pem
    # set RequestHeader to your prosody http_host.
    # Its necessary if it is different from the ServerName like in this example:
    RequestHeader set Host "example.com"
    RequestHeader set X-Forwarded-Proto: https
    ProxyPreserveHost On

    ProxyPass / "http://127.0.0.1:5280/xmpp-websocket" upgrade=websocket timeout=900

    ProxyPass / "http://127.0.0.1:5280/http-bind" #for bosh
    ProxyPassReverse / "http://127.0.0.1:5280/http-bind"
</VirtualHost>

<VirtualHost *:443>
    ServerName share.example.com
    SSLEngine On
    SSLCertificateFile /path/to/certificatefolder/fullchain.pem
    SSLCertificateKeyFile /path/to/certificatefolder/privkey.pem

    ProxyPreserveHost On
    RequestHeader set X-Forwarded-Proto: https
    #here the RequestHederHost is already the same as the Component name.
    ProxyPreserveHost On
    ProxyPass / "http://127.0.0.1:5280/"
    ProxyPassReverse / "http://127.0.0.1:5280/"
</VirtualHost>

VirtualHost "example.com"
-- ... optional unrelated settings ...

Component "share.example.com" "http_file_share"
    -- its not nessesary to have s2s loaded here:
    modules_disabled = { "s2s" }
    -- Change the Limit to 100MB:
    http_file_share_size_limit = 1024 * 1024 * 100
    http_file_share_expires_after = "2 weeks"
    -- Set it to the same as the apache host above:
    http_external_url = "https://share.example.com/"
    -- here you see how we can manipulate the path:
    http_paths = {
        file_share = "/"; --Serve from the base URL
 }

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.