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 | service |
---|---|
5000/tcp | File transfer proxy |
5222/tcp | Client connections |
5269/tcp | Server-to-server connections |
5280/tcp | HTTP |
5281/tcp | HTTPS |
5347/tcp | External components |
5582/tcp | 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:
= { "127.0.0.1" } -- Listen only for local connections interfaces
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
:
= { "::1" } local_interfaces
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:
= { 5222, 5322 } -- Listen on 5322 as well as 5222
c2s_ports = { "192.168.0.1", "::1" } -- Listen only on these interfaces c2s_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 = "/path/to/certificate.key";
key = "/path/to/certificate.crt";
certificate }
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"] = {
= "/path/to/certificate.key";
key = "/path/to/certificate.crt";
certificate };
["192.168.0.1"] = {
= "/path/to/other-certificate.key";
key = "/path/to/other-certificate.crt";
certificate };
-- or by ports, if more convenient:
[5285] = {
= "/path/to/another-certificate.key";
key = "/path/to/another-certificate.crt";
certificate };
}
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: select (default), libevent and epoll.
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 = 300;
read_timeout = 5;
tcp_backlog }
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. |