How to Install and Configure Prosody XMPP Server on Ubuntu 16.04/17.04

Prosody is a free open-source XMPP server written in Lua. It’s fast and lightweight. XMPP is a great protocol for instant messaging. This tutorial is going to show you how to install and configure Prosody XMPP server on Ubuntu 16.04/17.04. Once you have finished this tutorial, you will have you own chat server.

How to Install Prosody on Ubuntu 16.04/17.04

Prosody is included in the default Ubuntu repository, so it’s very easy to install. Simply open up a terminal window and execute the following command.

sudo apt install prosody

The Prosody team also maintains an APT repository. If you want to get the latest version, then you need to add the Prosody repo. Create a source file for Prosody.

sudo nano /etc/apt/sources.list.d/prosody.list

Add the following line into the file.

deb xenial main

Save and close the file. Then run the following command to download and import Prosody public key, which allows APT package manager to verify the integrity of packages downloaded from this repository.

wget -O- | sudo apt-key add -

Next, update local package index and install the latest version of Prosody.

sudo apt update

sudo apt install prosody

Once installed, Prosody can be started and stopped with:

sudo systemctl start prosody

sudo systemctl stop prosody

To enable auto start at system boot time, run

sudo systemctl enable prosody

Similarly, to disable auto start at boot time, run

sudo systemctl disable prosody

How to Configure Prosody XMPP Server

Edit the main configuration file with nano or your preferred command line text editor.

sudo nano /etc/prosody/prosody.cfg.lua

In module_enabled {...} section, you can uncomment a line to enable a specific module, or comment out a line to disable a specific module. Each module has a description telling you what it does. An example of enabled modules is as follows. (Comment left out.)

modules_enabled = {

Most of the above modules are enabled by default except for bosh, which stands for Bidirectional-streams Over Synchronous HTTP. It allows XMPP communication over HTTP.

Configuring a Virtual Host

Below is an example virtual host configuration. Make sure the prosody user has permission to read your key and certificate.

VirtualHost ""
      enabled = true  
      ssl = {
          key = "/etc/prosody/certs/your-privkey.pem";
          certificate = "/etc/prosody/certs/your-cert.pem"; }

Enabling SSL/TLS

In the ssl {...} section,  replace the placeholder with your own key and certificate.

ssl = {
   key = "/etc/prosody/certs/localhost.key";
   certificate = "/etc/prosody/certs/localhost.crt";

Then set the values of the following two parameter to true. This enforce client-to-server and server-to-server communication encrypted.

c2s_require_encryption = true;

s2s_secure_auth = true;

Setting up BOSH

If you want to enable BOSH, then you need to enable the bosh module in modules_enabled {...} section and add the following two lines at the end of the file.

consider_bosh_secure = true;
cross_domain_bosh = true;

The second line adds COR headers to BOSH responses to allow requests to come from any domain. The BOSH endpoint will be available at the following address once you finish this tutorial. port 5280 is for plain text HTTP, port 5281 for HTTPS.


A BOSH endpoint is a URL that is used by a client to connect to XMPP server over HTTP.

prosody bosh setup

Enabling Registration from XMPP Client

If you want to allow registration from XMPP client, then you need to enable the register module in modules_enabled {...} section. After that, set allow_registration to true.

allow_registration = true;

Restarting Prosody

After making changes to the configuration file, save and close it. Then check if the syntax is correct by running:

luac -p /etc/prosody/prosody.cfg.lua

If syntax is correct, restart Prosody.

sudo systemctl restart prosody

Creating User Accounts

User account for Prosody XMPP server can be created using the following command. You will be prompted to enter a password.

sudo prosodyctl adduser [email protected]

To change password, run

sudo prosodyctl passwd [email protected]

Once you have created an account, you can test this with an XMPP client.

Configuring the Client

This tutorial uses Pidgin instant messenger as the XMPP client. Empathy is another client you can use. They can be installed on an Ubuntu workstation by running:

sudo apt install pidgin

sudo apt install empathy

Upon first launch, you will need to add an account in Pidgin. Click Add button.

prosody xmpp ubuntu 16.04

Then select XMPP from the list of protocols and enter your username, domain and password.

install prosody on ubuntu 16.04

Hit the Add button and you will be logged in.

Multi-User Chat Room

To enable a MUC (Multi-User Chat), add the following line in the Prosody configuration file. Replace with your preferred domain name.

Component "" "muc"
     restrict_room_creation = "admin"

The second line will allow only admin to create rooms. To define admin for the XMPP server, first you need to create account using the sudo prosodyctl adduser command as shown above. Then in the configuration file, add the account in admin {...} section like below.

admins = { "[email protected]", "[email protected]" }

Prosody Log Files

The main log file for Prosody is /var/log/prosody/prosody.log. There’s also an error log /var/log/prosody/prosody.err. If Prosody isn’t working as you expected, the error log is a good place to check.

That’s it! I hope this tutorial helped you install and configure Prosody XMPP server on Ubuntu 16.04/17.04.

Rate this tutorial
[Total: 5 Average: 4]