How to Set Up Prosody XMPP Server on Ubuntu 22.04

echo "deb [signed-by=/etc/apt/keyrings/prosody-debian-packages.key] https://packages.prosody.im/debian $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/prosody.list

wget --quiet -O - https://prosody.im/files/prosody-debian-packages.key | sudo tee /etc/apt/keyrings/prosody-debian-packages.key

sudo apt update

sudo apt install prosody

systemctl status prosody

● prosody.service - Prosody XMPP Server
     Loaded: loaded (/lib/systemd/system/prosody.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2022-07-15 17:00:43 HKT; 33s ago
       Docs: https://prosody.im/doc
   Main PID: 210690 (lua)
      Tasks: 1 (limit: 9410)
     Memory: 8.9M
        CPU: 714ms
     CGroup: /system.slice/prosody.service
             └─210690 lua /usr/bin/prosody -F

sudo systemctl start prosody

sudo systemctl enable prosody

sudo ss -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 command.

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 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 prosody apache2

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

@daily certbot renew --quiet && systemctl reload prosody nginx

Reloading Prosody 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 22.04. As always, if you found this post useful, then subscribe to our free newsletter to get more tips and tricks 🙂