This tutorial will help you to install an instant messaging server with Prosody. Prosody is a communication server using the protocol XMPP which allows for instant messaging either for you or for your business, it is usable on all terminal types. Using a standard protocol let use it with any XMPP client.

Info : a list of XMPP clients more or less up to date is available on Wikipedia. Personally, I use Gajim on Linux and Jitsi on Windows.


You will only need a Linux server with a root access. I will also explain how to link accounts to Active Directory.

Installation of Prosody

Method 1

To install Prosody, you can do it via the packages :

sudo apt-get update
sudo apt-get install prosody

Ubuntu Server ( 14.04.4 LTS ), the deposit is up to date and offers the latest version.

Method 2

You can also add the repos of Prosody which will be easier to maintain :

echo deb $(lsb_release -sc) main | sudo tee -a /etc/apt/sources.list
wget -O- | sudo apt-key add -
sudo apt-get update
sudo apt-get install prosody


You will have now set Prosody. The first thing to do is create a VirtualHost in a configuration file. Prosody configuration files are ended with .lua.

Go to the Prosody directory and look at what is in folders :

cd /etc/prosody
ls -l

You should have the following folders:

  • certs that will contains your certificates and keys.
  • conf.d which will be active configurations (much like Apache or Nginx system) using symbolic links.
  • conf.avail : available configuration files.

You will now create a configuration file.

Replace by the name of your domain to match your configuration. In this tutorial, we’ll use email, so users log in with their email instead of their Active Directory login. Also it displays the status of the people in Outlook (if you have Jitsi). So I’ll make it with mail for this tutorial.

# If folder does not exist
sudo mkdir conf.avail
# Create configuration file
sudo vi conf.avail/

Then copy the following lines :

--- Virtual hostname ---
VirtualHost ""

--- Components ---
Component "" "muc"
    name = "Room server for"
    restrict_room_creation = "admin"

Your virtual hostname will be the address to use to connect : eg ``.

You can also disable the host by adding the line enabled = false after.

The Components are modules that you can add to the prosody server. In this case, a MUC is defined (“Multi-user Chat” : in short, a “room”), with corresponding addresses (

Putting admin for restrict_room_creation only allows administrators to create persistent room ! This means that other users can only create temporary conferences. Most XMPP client then propose administrators to configure the rooms as they wish. If you do not want this feature, simply delete the line.


Here’s how to set an administrator for Prosody. Open the main configuration file (sudo vi prosody.cfg.lua) and add your user. You can also take the opportunity to browse the file. It is fairly well explained.

admins = { "" }

Prosody can manage authentication with your AD server. As said above, we will ensure that people can connect with their email. To achieve this, it is necessary that email is obviously set in your AD for each user.

To manage authentication, we need [ Cyrus ] ( ). Here’s how to install it :

sudo apt-get install lua-cyrussasl sasl2-bin

Then we will indicate this in our configuration ( vi conf.avail/ Now your file should look like this :

--- Nom de l'hôte virtuel ---
VirtualHost ""

modules_enabled = {

allow_registration = false;

c2s_require_encryption = true
s2s_secure_auth = true

authentication = "cyrus"

allow_unencrypted_plain_auth = true

You must then edit the saslauthd configuration file ( sudo vi /etc/default/saslauthd) :

# Here we set the ldap option file

Now, define the options with which saslauthd will connect to your AD . Add and edit the file / etc / saslauthd.conf :

ldap_servers: ldap://ip_server
ldap_search_base: dc=domain,dc=com

ldap_bind_dn: DOMAIN\user
ldap_bind_pw: password
ldap_start_tls: no
ldap_auth_method: bind

# Filter below is for connections with username
# ldap_filter: (samAccountName=%U)
# Here we use mail instead :
ldap_filter: (

Replace the various data with your own configuration, save and exit.

Test authentication

You must restart the service saslauthd :

sudo service saslauthd restart

Now you can test the setup with the following command :

# In case the user has an email ""
sudo testsaslauthd -u u.user -p password

If you have the following output : 0: OK "Success" your authentication works. Otherwise, check out your options for saslauthd and if you have installed all dependencies.

Prosody and Sasl

So that the user has access to the prosody saslauthd socket, we take care to add it to sasl group :

sudo gpasswd -a prosody sasl

You can verify that the user has access to prosody saslauthd :

sudo su prosody -s /bin/bash
/usr/sbin/testsaslauthd -u u.user -p password

Finally, we must add one last configuration file in /etc/sasl/. The folder probably does not exist, you will need to create :

cd /etc/
sudo mkdir sasl
# Then edit the following file
sudo vi /etc/sasl/prosody.conf

Add the this two lines :

pwcheck_method: saslauthd
mech_list: PLAIN

Save and quit.

Restart saslauthd and prosody service :

sudo service saslauthd restart
sudo service prosody restart

Test a client

You will now be able to test with a client (Gajim, Jitsi, Pidgin…). You simply enter :

  • IP XMPP server, leaving port 5222.
  • Your credentials : email and password
  • Accept the certificate

In most clients you can configure a proxy if necessary.

Normally, the connection is expected to pass and your status should be connected ! If this is not the case, look at your logs :

sudo tail -f /var/log/prosody/prosody.log
# or
sudo tail -f /var/log/prosody/prosody.err

The files of logs can be defined in the prosody.cfg.lua file.

Manage Certificates

With Prosody, you can define certificate (self-signed or not) for each VirtualHost. In the main configuration file (prosody.cfg.lua), you should have the following lines :

-- These are the SSL/TLS-related settings. If you don't want
-- to use SSL/TLS, you may comment or remove this
ssl = {
    key = "/etc/prosody/certs/localhost.key";
    certificate = "/etc/prosody/certs/localhost.crt";

These lines indicate the path to the key and certificate to the localhost server and Prosody server. It is therefore defined two times. As you can see, the localhost server is disabled ( enabled = false). So it should not bother us.

By cons, for your new virtual server (, it would be redefined.

The goal here is to have a certificate authority (localhost) and therefore our sign other certificates.

Install Lua-expat 1.3

If you have a version problem for lua-expat, you must add the repository universe of vivid (sudo vi /etc/apt/sources.list) :

deb vivid main universe

Then updates the deposits and install lua-expat :

sudo apt-get update
sudo apt-get install lua-expat

Note : during the update packages, it is possible that you have errors. Install lua-expat and then you can comment out the line added in sources.list.

Generate a request file

Now in order to generate our ssl certificate for our virtual host, you must have a request file :

sudo prosodyctl cert request

Type Enter to validate data by default or enter new information. It should look something like this :

Choose key size (2048):
Generating RSA private key, 2048 bit long modulus
e is 65537 (0x10001)
Key written to /var/lib/prosody/
Please provide details to include in the certificate config file.
Leave the field empty to use the default value or '.' to exclude the field.
countryName (FR):
localityName (The Internet):
organizationName (Your Organisation): MyBusiness
organizationalUnitName (XMPP Department): DSI
commonName (
emailAddress (

Config written to /var/lib/prosody/
Certificate request written to /var/lib/prosody/

Sign with the CA

The certificate authority will now help us to create and sign our key :

sudo openssl x509 -req -days 730 -in /var/lib/prosody/ -CA /etc/prosody/certs/localhost.crt -CAkey /etc/prosody/certs/localhost.key -set_serial 01 -out /var/lib/prosody/

You should have the following output :

Signature ok
subject=/C=FR/L=The Internet/O=MyBusiness/OU=DSI/
Getting CA Private Key

Add Certificate

Now that we have a lovely self-signed certificate, we can add it to our VirtualHost. Open the configuration file (sudo vi conf.avail/ and add it as follows :

ssl = {
        key = "/var/lib/prosody/";
        certificate = "/var/lib/prosody/";

Note : be careful to add these lines after the declaration of VirtualHost. If you add them before, it will not work.

Now you can restart prosody :

sudo service prosody restart

During the reconnection of your client, you should have a new acceptance of the certificate request. You can display it to see the data you enter above.

Confirm and agree . Check the box ignore if you do not want to have this warning.

You can then repeat these operations if you have other virtual hosts to add. Well sign your certificates with the same authority (localhost in this case) !

Other possibilities

Prosody allows for many things, like create persistent rooms, display welcome messages , receive files etc …

The Rooms

For the creation of rooms, you normally have written the following lines at the beginning of the tutorial :

--- Components ---
Component "" "muc"
    name = "Serveur de Salons pour"
    restrict_room_creation = "admin"

This means that the creation of rooms will be possible only by administrators. Moreover, the rooms are created by the client !

You will have the option in your client to define whether the show is permanent, open, protected by a password,… Other people connected can then search for available rooms in their client and connect if they have the sufficient rights.

Word of the Day

You can set a word of day, adding the following line (in prosody.cfg.lua) :

motd_text = [[Welcome on Instant messaging server.]]

Restart prosody to apply the change.

Plugins Paths

If you take the urge to add more plugins, you can set the path thereof through the following :

plugin_paths = { "/usr/lib/prosody/modules", "/usr/lib/prosody/prosody-modules"}

Restart prosody to apply the change.


In the end, Prosody is very comprehensive. There are obviously other XMPP server but I find that Prosody provides everything you need for instant messaging and allows you to configure your connections accurately.