How to Set Up Prosody XMPP Server on Ubuntu 20.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 20.04. Once you have finished this tutorial, you will have your own chat server.

Step 1: Install Prosody on Ubuntu 20.04

Prosody is included in the default Ubuntu repository. The Prosody team also maintains a package repository. If you want to get the latest version, then you need to add the Prosody repository with the following command.

echo 'deb https://packages.prosody.im/debian focal main' | sudo tee /etc/apt/sources.list.d/prosody.list

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 https://prosody.im/files/prosody-debian-packages.key -O- | sudo apt-key add -

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

sudo apt update

sudo apt install prosody

Once installed, Prosody will automatically start. You can check its status with:

systemctl status prosody

Output:

● prosody.service - Prosody XMPP Server
   Loaded: loaded (/lib/systemd/system/prosody.service; enabled; vendor preset: enabled)
   Active: active (running) since Sun 2020-04-19 13:58:40 UTC; 16s ago
     Docs: https://prosody.im/doc
 Main PID: 1894 (lua5.2)
    Tasks: 1 (limit: 1108)
   CGroup: /system.slice/prosody.service
           └─1894 lua5.2 /usr/bin/prosody -F

Apr 19 13:58:40 localhost systemd[1]: Started Prosody XMPP Server.

If it’s not running, you can start it with

sudo systemctl start prosody

To enable auto-start at system boot time, run

sudo systemctl enable prosody

Step 2: Opening Ports in the Firewall

By default, it listens on TCP port 5269 and 5222 of the public IP address, as can be seen with the following command. (If your Ubuntu doesn’t have the netstat command, you can install it with sudo apt install net-tools.)

sudo netstat -lnptu | grep lua

• Port 5222 is used for client to server connection.
• Port 5269 is used for server to serer connection.

If you have enabled the UFW firewall on Ubuntu, then you need to open the above ports with the following command.

sudo ufw allow 5222,5269/tcp

Step 3: Configure Prosody XMPP Server

Edit the main configuration file with a command line text editor such as Nano.

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. You probably want to enable the BOSH module, which stands for Bidirectional-streams Over Synchronous HTTP. It allows XMPP communication over HTTP.

Next, scroll down in the configuration file. If you want to allow account registration from XMPP client, then set allow_registration to true. Note that you must know how to prevent abuse before doing this. If you are new to XMPP, you probably don’t want to allow XMPP clients to register accounts by themselves.

allow_registration = true;

Prosody only allows encrypted communication, indicated by the following two lines.

c2s_require_encryption = true

s2s_require_encryption = true

However, we need to create a virtual host and install TLS certificate, so connections can be encrypted. By default, there’s only one virtual host in Prosody: localhost, as indicated by the following line.

VirtualHost "localhost"

Now we create another virtual host like chat.example.com. Add the following line in this file.

VirtualHost "chat.example.com"

Save and close the file. Then we need to obtain and install a trusted TLS certificate from Let’s Encrypt.

Step 4: Obtain a Trusted TLS certificate from Let’s Encrypt

Issue the following command to install Let’s Encrypt client (certbot) on Ubuntu server.

sudo apt install certbot

If you don’t have a web server running yet, I recommend you install one (Apache or Nginx), because it’s easier to obtain and install TLS certificate with a web server than using other methods.

If you use Apache web server, you need to install the Apache plugin. (The following command will install Apache web server if it’s not already installed on your system.)

sudo apt install python3-certbot-apache

If you use Nginx web server, then install the Nginx plugin. (The following command will install Nginx web server if it’s not already installed on your system.)

sudo apt install python3-certbot-nginx

Obtaining TLS Certificate with Apache Web Server

You need to have an Apache virtual host for chat.example.com before obtaining Let’s Encrypt TLS certificate. Create the virtual host file:

sudo nano /etc/apache2/sites-available/prosody.conf

Then paste the following text into the file. Replace chat.example.com with your real domain name. Don’t forget to set DNS A record for it.

<VirtualHost *:80>        
        ServerName chat.example.com

        DocumentRoot /var/www/prosody
</VirtualHost>

Save and close the file. Then create the webroot directory.

sudo mkdir /var/www/prosody

Set www-data (Apache user) as the owner of the webroot.

sudo chown www-data:www-data /var/www/prosody -R

Enable this virtual host.

sudo a2ensite prosody.conf

Reload Apache for the changes to take effect.

sudo systemctl reload apache2

Once the virtual host is created and enabled, run the following command to obtain and install Let’s Encrypt TLS certificate.

sudo certbot --apache --agree-tos --redirect --hsts --staple-ocsp --email [email protected] -d chat.example.com

Substitute the red text with your actual data. You should see the following which means the certificate is successfully obtained. You can also see the directory under which your cert is stored.

Obtaining TLS Certificate with Nginx Web Server

You need to have an Nginx virtual host for chat.example.com before obtaining Let’s Encrypt TLS certificate. Create the virtual host file:

sudo nano /etc/nginx/conf.d/prosody.conf

Next, paste the following text into the file. Replace chat.example.com with your real domain name. Don’t forget to set DNS A record for it.

server {
      listen 80;
      listen [::]:80;
      server_name chat.example.com;

      root /var/www/prosody/;

      location ~ /.well-known/acme-challenge {
         allow all;
      }
}

Save and close the file. Then create the web root directory.

sudo mkdir /var/www/prosody/

Set www-data (Nginx user) as the owner of the web root.

sudo chown www-data:www-data /var/www/prosody -R

Reload Nginx for the changes to take effect.

sudo systemctl reload nginx

Once the virtual host is created and enabled, run the following command to obtain and install Let’s Encrypt certificate with Nginx plugin.

sudo certbot --nginx --agree-tos --redirect --hsts --staple-ocsp --email [email protected] -d chat.example.com

You should see the following which means the certificate is successfully obtained. You can also see the directory under which your cert is stored.

Step 5: Install TLS Certificate in Prosody

Edit the main configuration file.

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

Go to your Prosody virtual host and add the TLS certificate and key file.

ssl = {
      key = "/etc/letsencrypt/live/chat.example.com/privkey.pem";
     certificate = "/etc/letsencrypt/live/chat.example.com/fullchain.pem";
}

Like this:

Save and close the file. Since Prosody XMPP server runs as the prosody user, we need to allow the prosody user to read the TLS certificate and key file with the following commands.

sudo apt install acl
sudo setfacl -R -m u:prosody:rx /etc/letsencrypt/

Step 6: Create 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]

Step 7: Restart Prosody

Check the configuration file syntax by running:

sudo prosodyctl check config

If syntax is correct, restart Prosody for the changes to take effect.

sudo systemctl restart prosody

Step 8: Configure XMPP 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 desktop by running:

sudo apt install pidgin

sudo apt install empathy

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

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

Hit the Add button and you will be logged in.

Set up BOSH

As we previously explained, BOSH allows you to use XMPP over HTTP, i.e, in a web browser. For example, the Jitsi Meet video conference software uses BOSH to integrate Prosody in web pages, so attendees can text chat while joining an online video meeting.

If you enabled the BOSH module, then edit the Prosody configuration file (/etc/prosody/prosody.cfg.lua) and add the following two lines at the end of the configuration file.

consider_bosh_secure = true;
cross_domain_bosh = true;
https_ssl = {
        certificate = "/etc/letsencrypt/live/chat.example.com/fullchain.pem";
        key = "/etc/letsencrypt/live/chat.example.com/privkey.pem";
    }

Where:

• The first line enforces secure HTTPS connection.
• The second line adds COR headers to BOSH responses to allow requests to come from any domain.
• The https_ssl parmater specifies the TLS certificate and key file for the BOSH service.

Save and close the file. Then restart Prosody.

sudo systemctl restart prosody

If you have enabled the UFW firewall on Ubuntu server, then you need to open port 5280 and 5281 with the following command.

sudo ufw allow 5280,5281/tcp

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.

http://chat.example.com:5280/http-bind

or

https://chat.example.com:5281/http-bind.

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

Multi-User Chat Room

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

Component "conference.example.com" "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]" }

Check the configuration file syntax by running:

sudo prosodyctl check config

If syntax is correct, restart Prosody for the changes to take effect.

sudo systemctl restart prosody

Troubleshooting

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.

Auto-Renew TLS Certificate

You can create Cron job to automatically renew TLS certificate. Open root user’s crontab file.

sudo crontab -e

If you use Apache web server, add the following line at the bottom of the file.

@daily certbot renew --quiet && systemctl reload postfix dovecot apache2

If you are using Nginx web server, then add the following line.

@daily certbot renew --quiet && systemctl reload postfix dovecot nginx

Reloading Postfix, Dovecot and the web server is necessary to make these programs pick up the new certificate and private key.

Wrapping Up

That’s it! I hope this tutorial helped you install and configure Prosody XMPP server on Ubuntu 20.04. As always, if you found this post useful, then subscribe to our free newsletter to get more tips and tricks 🙂