Configuring Prosody

Prosody's configuration is held in a single file, prosody.cfg.lua. If you install Prosody under GNU/Linux then you should find it in /etc/prosody/prosody.cfg.lua. On Mac OS X installed via Homebrew you should find it in /usr/local/etc/prosody/prosody.cfg.lua. On other systems, or when not installed, it will be under the same directory as the prosody main executable.

An Example configuration file for Prosody file is given, with a .dist extension. It is thoroughly commented, and can serve as the base for your own.

For changes to take effect, you will usually need to either restart prosody or reload the configuration and affected modules via one of the admin interfaces like mod_admin_adhoc or the telnet console.

Overview

The configuration is divided into two parts. The first part is known as the "global" section. All settings here apply to the whole server, and are the default for all virtual hosts.

The second half of the file is a series of VirtualHost and Component definitions. Settings under each VirtualHost or Component line apply only to that host.

example_setting = "this is a global setting"

VirtualHost "example.com"
example_setting = "this applies only to 'example.com'"

Component "groups.example.com" "muc"
example_setting = "applies only to this component"

Simple settings in each section has the following syntax:

example_number = 12345
example_string = "hello"
enabled = true

More complex settings can structured using lists and maps:

example_list = {
    "this";
    "that";
    "finally this";
}
example_map = {
    this = "that";
    some = 7;
}

First time users

The only thing you are required to configure now is the hosts/domains you wish Prosody to serve, see the next section "Adding a host".

Adding a host

A host in Prosody is a domain on which user accounts can be created. For example if you want your users to have addresses like john.smith@example.com then you need to add a host "example.com".

Adding a virtual host to the server is as easy as adding a line to the configuration file under the global settings. For example.org, one would add:

VirtualHost "example.org"

All options under this heading will apply only to this host until another VirtualHost or Component entry, so be sure to add it in the right place after all the global options.

Note: The name "virtual" host is used in configuration to avoid confusion with the actual physical host that Prosody is installed on. A single Prosody instance can serve many domains, each one defined as a VirtualHost entry in Prosody's configuration. Conversely a server that hosts a single domain would have just one VirtualHost entry.

Creating accounts

Now you have your server configured and serving your domain you need to create some user accounts. The multiple ways of creating accounts into your Prosody server are described on our page 'Creating accounts'.

Adding components/services

Components are extra services your server can provide, usually on subdomains of the main server. They provide functionality such as Chatrooms, and transports/gateways to other networks and protocols.

Prosody has a number of built-in components, an example is the MUC (Multi-User Conference) component for running chatrooms.

Component "conference.example.org" "muc"

This example sets up a MUC chatroom service at "conference.example.org", which you can then join rooms on using your client.

Prosody also supports external server-independent components if they support XEP-0114. You can get more help on our page 'Configuring components', including how to add external components and other component options.

Core options

General server settings

These settings describe the general running of Prosody, and only work in the global section of the config file.

log: Set logging options. May be a filename, or if mod_posix is loaded it may be “*syslog”. Advanced logging configuration is possible to send different messages to different places, see Logging Configuration for more details.
data_path: Location of the Prosody data storage directory, without a trailing slash. The default path depends on your system and how you installed Prosody. If you installed from packages on a Linux-based platform, this is usually /var/lib/prosody.

If you are running Prosody from source, the default data path is "./data", and you can change the default at build time by passing the –datadir option to ./configure like so: ./configure –datadir=/var/lib/prosody

Port and network settings

Because open ports are per-system, these settings affect the whole server and can only be present in the global section of the config file. You can find full information about configuring the network side of Prosody in our port and network configuration documentation.

All <name>_ports and <name>_interfaces settings are lists, wrapped in { } brackets:

foobar_ports = { 1234 }
barfoo_ports = { 4321, 2345 }
no_ports = {}

foobar_interfaces = { "::", "0.0.0.0" }
no_interfaces = {}

Here we list the most common options to get you started.

Client-to-server

Provided by mod_c2s.

c2s_ports: Ports on which to listen for client connections. Default is { 5222 }
c2s_interfaces: Interfaces on which to listen for client connections. Defaults to default interfaces.
c2s_timeout: Timeout unauthenticated client connections. Defaults to 300 i.e. 5 minutes.
legacy_ssl_ports: Ports on which to listen for SSL connections. Disabled by default.
legacy_ssl_interfaces: Interfaces on which to listen for legacy SSL connections. Defaults to default interfaces.
c2s_direct_tls_ports: Ports on which to listen for XMPP over TLS client connections. Disabled by default. Available starting with 0.12.0.
c2s_direct_tls_interfaces: Interfaces on which to listen for XMPP over TLS client connections. Defaults to default interfaces. Available starting with 0.12.0.

Server-to-server

Provided by mod_s2s.

s2s_ports: Ports on which to listen for server-to-server connections. Default is { 5269 }
s2s_interfaces: Interfaces on which to listen for server-to-server connections. Defaults to default interfaces.
s2s_timeout: Timeout for unauthenticated server connections. Default is 90 seconds.
s2s_direct_tls_ports: Ports on which to listen for XMPP over TLS server-to-server connections. Disabled by default. Available starting with 0.12.0.
s2s_direct_tls_interfaces: Interfaces on which to listen for XMPP over TLS server-to-server connections. Defaults to default interfaces. Available starting with 0.12.0.

HTTP and HTTPS

Provided by mod_http and documented on the HTTP server page.

Encryption and security settings

Certificates

Certificates are automatically located, and we recommend that you use this feature instead of manually specifying a location in the config file.

If you are using Let's Encrypt, please see this guide.

Other encryption options

tls_profile: One of “modern”, “intermediate” (default), “old” or “legacy”, Configures ciphers per corresponding profile from Mozilla
c2s_require_encryption: This will force encryption for client to server connections. May be true or false, defaults to true.
s2s_require_encryption: This will force encryption for server to server connections. May be true or false, defaults to true. Note that this does not enforce the use of certificates for authentication (which is required to be truly secure). For more info see our documentation on s2s security.

More info

Certificates: details of certificate creation and management
Security: advice on running a secure server

Virtual host settings

Note: Any of the options in this section can be put in the global section of the config file (i.e. before any VirtualHost or Component sections). They will then be applied to all hosts, unless they are overridden.

enabled: May be true or false. Specifies whether this host is enabled or not. Disabled hosts are not loaded and do not accept connections while Prosody is running.
modules_enabled: List of modules to load for the host (or for all hosts if in global section).

Example:

   modules_enabled = {
                       "dialback",
                       "roster",
                       "saslauth" }

Note that the mod_ prefix or the .lua file extension is not included.

modules_disabled: Allows you to disable the loading of a list of modules for a particular host, or all hosts if those modules are set in the global section. Same syntax as modules_enabled.
admins: List of administrators of the current host e.g.

admins = { "admin1@example.com", "admin2@example.com" }

authentication: Choose what authentication plugin will be used on this host (or all hosts if in the global section). Defaults to "internal_hashed". For more information see Authentication providers.

Sessions and resources

conflict_resolve: How to resolve resource conflicts. May be “random” (assign a random resource), “increment” (append a unique integer to the resource), “kick_new” (deny the new connection), “kick_old” (disconnect the existing session). Default is “kick_old”.
ignore_presence_priority: When set to true, Prosody will ignore the priority set by the client when routing messages. In effect any incoming messages to the user’s bare JID will be broadcast to all of the user’s connected resources instead of the one(s) with the highest priority.

Registration

To allow clients to create themselves accounts on your server (also known as "in-band" registration) you will need mod_register loaded. This usually means adding "register" to modules_enabled as described above. The options in this section only apply when mod_register is active.

An alternative way to create user accounts on non-Windows servers is to use prosodyctl.

allow_registration: Whether to allow registration of new accounts via Jabber clients. Default is false.

Additional options are documented on the mod_register page.

POSIX-only options

These options are for POSIX systems only, eg. GNU/Linux, BSD, and Mac OSX. Basically everyone except Windows 😄 Additionally they only work when mod_posix is loaded, that is, when "posix" is in the list of modules_enabled.

pidfile: File in which to write pid (process id) when daemonized. Default none.

For more options take a look at the mod_posix documentation.