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.


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.

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 then you need to add a host "".

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

VirtualHost ""

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 "" "muc"

This example sets up a MUC chatroom service at "", 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. On Windows, %APPDATA%\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.

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


Note: in 0.8 and older versions, these 'X_interfaces' options are called 'X_interface' and only supports listening on a single interface.


Provided by mod_c2s.

c2s_ports - Ports on which to listen for client connections.

c2s_interfaces - Interface on which to listen for client connections. Defaults to default interfaces. Note: in 0.8 and older versions, this option is called 'c2s_interface' and only supports listening on a single interface.

c2s_timeout - Timeout unauthenticated client connections. Off by default, no timeout.

legacy_ssl_ports - Ports on which to listen for SSL connections. Disabled by default.

legacy_ssl_interfaces - Interface on which to listen for legacy SSL connections. Defaults to default interfaces. Note: in 0.8 and older versions, this option is called 'legacy_ssl_interface' and only supports listening on a single interface.


Provided by mod_s2s.

s2s_ports - Ports on which to listen for server-to-server connections. Default is { 5269 }

s2s_interfaces - Interface on which to listen for server-to-server connections. Defaults to default interfaces. Note: in 0.8 and older versions, this option is called 's2s_interface' and only supports listening on a single interface.

s2s_timeout - Timeout for unauthenticated server connections. Default is 90 seconds.

Encryption and security settings

Certificates - 0.10+

Certificates are automatically located in 0.10, 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.

Certificates - 0.9

ssl - table Holds settings related to SSL/TLS security and encryption.

An example ssl setting is:

   ssl = { 
                key = "certs/";
                certificate = "certs/";

Other encryption options

c2s_require_encryption - This will force encryption for client to server connections. May be true or false, defaults to false.

s2s_require_encryption - This will force encryption for server to server connections. May be true or false, defaults to false. 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).


   modules_enabled = {
                       "saslauth" }

modules_disabled - Allows you to disable the loading of a list of modules for a particular host, 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 = { "", "" }

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

anonymous_login - Allow anyone to log into the server without a password using SASL ANONYMOUS (client must support it). When enabled, normal logins are not possible, and communication with remote domains is disabled by default for anonymous users. For more information see Configuring anonymous logins. Note: In 0.9, this is replaced by authentication = "anonymous".

disallow_s2s - Prevent users on this host (or all hosts if specified in the global section) from contacting remote servers. Default is false unless anonymous logins have been enabled (in which case it defaults to true). Note: In 0.9, this is accomplished by putting "s2s" in modules_disabled.

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.


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. A Windows utility for the same purpose is planned.

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.

daemonize - Enable automatic daemonization when mod_posix is loaded. Default is "true".

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

For more options take a look at the mod_posix documentation.

Common Tasks

doc/configure.txt · Last modified: 2017/09/23 18:22 by Matthew Wild