Prosody IM Website

file doc/ in changeset e4ef8c017cb2

View latest ↓ Download file

line wrap: on
line source

title: Prosody HTTP server

Prosody contains a mini built-in HTTP server, which is used for
[BOSH](/doc/setting_up_bosh) and other modules.

The following HTTP modules are supplied with Prosody:

-   [mod_bosh](/doc/modules/mod_bosh)
-   [mod_websocket](/doc/modules/mod_websocket) (in 0.10+)
-   [mod_http_files](/doc/modules/mod_http_files)
-   [mod_http_file_share](/doc/modules/mod_http_file_share) (in trunk)

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:

``` {.code .lua}
    modules_enabled = {

# Port configuration {#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:

``` {.code .lua}
    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

# HTTPS Certificate {#https_certificate}

## Prosody 0.10 and later

In Prosody 0.10 the HTTPS service supports automatic certificate
detection via [service
certificates](/doc/certificates#service_certificates), as well as the
`https_certificate` option.

``` {.lua}
https_certificate = "certs/"
-- key expected to be found in certs/

## 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:

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

Prosody's HTTPS server does not currently support SNI[^1], 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 {#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 {#setting_a_http_host}

To map a HTTP Host name to a specific VirtualHost:

``` {.code .lua}
    VirtualHost ""
    http_host = ""

::: {.alert .alert-warning}
[:warning:]{.icon} 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 {#setting_a_default_host}

In the global section of your config, specify:

``` {.code .lua}
    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 {#path_variables}

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

``` {.code .lua}
    http_paths = {
        register_web = "/register-on-$host";
    http_host = ""
    VirtualHost "" --
    VirtualHost "jabber.example" --

# Path configuration {#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:

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

# Running behind a reverse proxy {#reverse_proxy}

## External 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 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:

``` {.code .lua}
    http_external_url = ""

## Trusted reverse proxies {#trusted_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:

``` {.lua}
trusted_proxies = { "", "::1", "", }

Starting with **trunk**, Prosody also understands the
`X-Forwarded-Proto` header, and will consider the request secure if it
has the value`https` and comes from a trusted proxy. This removes the
need for `consider_bosh_secure` and similar settings.

# Adding HTTP-only hosts {#adding_http-only_hosts}

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

``` {.code .lua}
    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.

[^1]: This has been implemented in the upcoming version