Overview

As a general rule, any network-related options may only be specified in the global section of the configuration file. This is because they affect the whole server, and are not applicable to virtual hosts.

Default interfaces

By default Prosody will try to use all available network interfaces (IP addresses) on the system. It is possible to restrict to one or more interfaces by manually specifying them with the 'interfaces' option:

    interfaces = { "127.0.0.1" } -- Listen only for local connections

All plugins will use the default interfaces unless you override them.

The special interface "*" means "all IPv4 interfaces", and the special interface "::" means "all IPv6 interfaces". We have separate documentation to tell you more about IPv6 configuration.

Private interfaces

Some services, such as the telnet console and components are considered private and by default will listen only to local "loopback" interfaces. These default to ::1 and 127.0.0.1.

These can be changed by setting local_interfaces:

local_interfaces = { "::1" }

If the services specific option, eg console_interfaces is set then that takes priority over local_interfaces.

Ports

Each module that opens ports in Prosody has a default port (or possibly multiple), mentioned in its documentation. For example mod_c2s listens on port 5222, XMPP's standard port for client connections.

It is possible to override the port and interface settings for a module. Simply set *_ports or *_interfaces as required (replace the * with the module or service name). For example to customise the port and interface mod_c2s uses:

    c2s_ports = { 5222, 5322 } -- Listen on 5322 as well as 5222
    c2s_interfaces = { "192.168.0.1", "::1" } -- Listen only on these interfaces

SSL configuration

Some services use SSL encryption. For example mod_c2s also provides a 'legacy_ssl' service that can be configured. As well as the standard ports and interfaces options described above, SSL services also have a *_ssl option (replace the * with the service name). This allows you to set the Certificates and other SSL options on that port. By default the use the certificate settings from the 'ssl' option if it is specified, alternatively you can set per-service certificates:

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

Another common SSL service is https, where the certificates can be configured with the https_ssl option. Sometimes it is necessary to handle multiple virtual hosts with different certificates. This is possible, by using different interfaces or ports. The configuration needs to be specified like this:

    https_ssl = {
        --- You can specify certificates by interfaces:
        ["127.0.0.1"] = {
            key = "/path/to/certificate.key";
            certificate = "/path/to/certificate.crt";
        };
        ["192.168.0.1"] = {
            key = "/path/to/other-certificate.key";
            certificate = "/path/to/other-certificate.crt";
        };
        -- or by ports, if more convenient:
        [5285] = {
            key = "/path/to/another-certificate.key";
            certificate = "/path/to/another-certificate.crt";
        };
    }

We have further documentation on certificate configuration and other SSL options if you need them.

Multiplexing

Prosody allows you to run multiple services on each port, and will automatically detect the kind of connection that has been opened. It is important to note that if you use these options, the individual port options above will be disabled. More information can be found in our article on Port Multiplexing.

Advanced

It is possible to configure and tweak some low-level settings in Prosody’s network library. What options are available here depend on the connection backend you are using, there are currently three: epoll (new default), libevent and select (old default).

The settings here apply to *all* connections on the server, regardless of what type they are. In this section we refer to the remote end of the connection as the "peer", which may in fact be a client or another server.

The option to use is network_settings, and you can use it like this:

    network_settings = {
        read_timeout = 300;
        tcp_backlog = 5;
    }

Here are the most common settings you may want to tweak: