====== 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 other systems, or when not installed, it will be under the same directory as the prosody main executable.

An [[example config]] file is given, with a .dist extension. It is thoroughly commented, and can serve as the base for your own.

===== 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 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.

===== Adding 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 example.org, one would add:
<code lua>
   VirtualHost "example.org"
</code>
All options under this heading will apply **only** to this host. However note that some options can only work when applied globally to the whole server.

===== Creating accounts =====
The multiple ways of creating accounts into your Prosody server are described on our page '[[Creating accounts]]'.

===== Adding a component =====

Also straightforward. In the second half of the configuration file, under the global settings:
<code lua>
   Component "conference.example.org" "muc"
</code>
and so on. You can get more help on [[components|configuring components]].

===== 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|Logging Configuration]] for more details.

**data_path** - Location of the Prosody data storage directory, without a trailing slash. Default is "data", or the path set with ./configure --datadir=/path/to/data

==== Port and network settings ====
Because open ports are per-system, these settings affect the whole server can can only be present in the global section of the config file.

=== Standard ===

**c2s_ports** - Ports on which to listen for client connections. Default is { 5222 }

**c2s_interface** - Interface on which to listen for client connections. Default is "0.0.0.0"

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

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

**s2s_interface** - Interface on which to listen for server-to-server connections. Default is "0.0.0.0"

**s2s_timeout** - Timeout unauthenticated server connections. Default is 60 seconds.

**legacy_ssl_ports** - Ports on which to listen for SSL connections. Default is {} (ie. empty list, none).

**legacy_ssl_interface** - Interface on which to listen for legacy SSL connections. Default is "0.0.0.0"

=== Port multiplexing ===
Alternatively, 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 [[:doc:port_multiplexing]].

**ports** - A list of ports on which to listen for XMPP or HTTP connections (Prosody automatically detects which) (version 0.7+).

**ssl_ports** - The same as the 'ports' option, but implies that the connections will be encrypted with SSL (useful for HTTPS and legacy XMPP SSL).

==== Encryption and security settings ====

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

An example ssl setting is:
<code lua>
   ssl = { 
                key = "certs/example.com.key";
                certificate = "certs/example.com.crt";
         }
</code>

For more help configuring or troubleshooting SSL/TLS, please see [[:doc:advanced_ssl_tls|Advanced SSL/TLS Configuration]].


**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//.

==== 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:
<code lua>
   modules_enabled = {
                       "dialback",
                       "roster",
                       "saslauth" }
</code>

**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. <code lua>admins = { "admin1@example.com", "admin2@example.com" }</code>


**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 [[.:anonymous logins]].

**disallow_s2s** - Prevent users on this host (or all hosts if specified under Host "*") from contacting remote servers. Default is //false// unless [[.:anonymous logins]] have been enabled (in which case it defaults to //true//).

==== Sessions and resources ====

**max_resources** - The maximum number of connections a single user may have logged into the server. Defaults to 10.

**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]]. 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 [[doc:modules: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 [[doc:modules:mod_posix]] documentation.

===== Common Tasks =====

  *[[Creating accounts]]
  *[[Setting up BOSH]]
  *[[components|Configuring components]]
  *[[prosodyctl|Using prosodyctl]]
  *[[logging|Logging Configuration]]
  *[[doc:modules:mod_compression|Enable compression]]