Prosody IM Website


file doc/configure.md in changeset 9d21a58aae32

View latest ↓ Download file

line wrap: on
line source

---
title: 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](/doc/example_config) 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](/doc/modules/mod_admin_adhoc)
or [the telnet console](/doc/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.

# First time users {#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 {#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:

``` {.code .lua}
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 {#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](/doc/creating_accounts)\'.

# Adding components/services {#adding_componentsservices}

Components are extra services your server can provide, usually on
subdomains of the main server. They provide functionality such as
[Chatrooms](/doc/chatrooms), and
[transports/gateways](/doc/transports_and_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.

``` {.code .lua}
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](http://xmpp.org/extensions/xep-0114.html). You can
get more help on our page \'[Configuring components](/doc/components)\',
including how to add external components and other component options.

# Core options {#core_options}

## General server settings {#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](/doc/logging) 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 {#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](/doc/ports).

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

### Standard

#### Client-to-server

Provided by [mod\_c2s](/doc/modules/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](/doc/ports#default_interfaces).

**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](/doc/ports#default_interfaces).

#### Server-to-server

Provided by [mod\_s2s](/doc/modules/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](/doc/ports#default_interfaces).

**s2s\_timeout** - Timeout for unauthenticated server connections.
Default is 90 seconds.

## Encryption and security settings {#encryption_and_security_settings}

### Certificates - 0.10+ {#certificates_-_010}

Certificates are automatically located in 0.10, and we recommend that
you [use this feature](/doc/certificates#automatic_location) instead of
manually specifying a location in the config file.

If you are using Let\'s Encrypt, please see [this
guide](/doc/letsencrypt).

### Certificates - 0.9 {#certificates_-_09}

**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";
         }
```

### Other encryption options {#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](/doc/s2s#security).

### More info {#more_info}

-   [Certificates](/doc/certificates): details of certificate creation
    and management
-   [Security](/doc/security): advice on running a secure server

## Virtual host settings {#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" }
```

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, 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" }
```

**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](/doc/authentication).

## Sessions and resources {#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](/doc/modules/mod_register) loaded. This usually means
adding \"register\" to [modules\_enabled](/doc/modules_enabled) as
described above. The options in this section only apply when
[mod\_register](/doc/modules/mod_register) is active.

An alternative way to create user accounts on non-Windows servers is to
use [prosodyctl](/doc/prosodyctl).

**allow\_registration** - Whether to allow registration of new accounts
via Jabber clients. Default is false.

Additional options are documented on the
[mod\_register](/doc/modules/mod_register) page.

## POSIX-only options {#posix-only_options}

These options are for POSIX systems only, eg. GNU/Linux, BSD, and Mac
OSX. Basically everyone except Windows [:smile:]{.icon} 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](/doc/modules/mod_posix)
documentation.

# Common Tasks {#common_tasks}

-   [Creating accounts](/doc/creating_accounts)
-   [Setting up a BOSH server](/doc/setting_up_bosh)
-   [Configuring components](/doc/components)
-   [Using prosodyctl](/doc/prosodyctl)
-   [Logging Configuration](/doc/logging)