Port and network configuration


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 = { "" } -- 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

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.


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 = { "", "::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:
        [""] = {
            key = "/path/to/certificate.key";
            certificate = "/path/to/certificate.crt";
        [""] = {
            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.


Prosody 0.7 and above allow you to run multiple services on each port, Prosody 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.


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 two: select (default) and libevent.

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. Behaviour when the timeout is hit depends on the Prosody version. 0.9 and earlier will disconnect the peer unconditionally, 0.10 will take appropriate action depending on the connection type and what 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.

doc/ports.txt · Last modified: 2016/12/23 11:36 by Kim Alvefur