Port and network configuration

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 ports

Here is an overview of default ports and the respective services:

port interfaces service
5000/tcp public File transfer proxy
5222/tcp public Client connections
5269/tcp public Server-to-server connections
5280/tcp private1 HTTP
5281/tcp public HTTPS
5347/tcp private External components
5582/tcp private Telnet console

As a rule of thumb, Prosody uses almost exclusively TCP for all its network communication. Rare exceptions (such as cooperating external services, e.g. TURN) mention the protocol they use in their own documentation.

Of the ports above, the https port uses standard TLS, the http port is unencrypted, and “Client connections” and “Server-to-server connections” ports use plain TCP by default, but can upgrade a connection using the STARTTLS option. “External components” and “Telnet console” only ever listen on a local interface.

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:

Name Backend Description
read_timeout All The number of seconds to allow peers to be silent for. Prosody will take appropriate action when the timeout is hit depending on the connection type and which plugins are installed.
send_timeout All The number of seconds to allow data to wait for a peers to receive it. The peer will be disconnected when this timeout triggers.
max_send_buffer_size All The maximum size, in bytes, of our (per-connection) send buffer. This is in addition to the send buffer provided by the OS. If the buffer increases above this limit, the peer will be disconnected.
tcp_backlog All This number is passed to the OS as the desired size of our 'backlog'. Interpretations of what it means vary, but if you have trouble dealing with large numbers of incoming connection attempts at once, try tweaking this value. Default is 32.

  1. unencrypted http port was public until it was changed to private with the release of Prosody 0.12.0↩︎