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

Step 1: Install Prosody on Ubuntu 22.04

Prosody is included in the default Ubuntu repository, but it’s very out of date. The Prosody team 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 [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

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

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

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, Prosody listens on TCP port 5269 and 5222 of the public IP address, as can be seen with the following command.

sudo ss -lnptu | grep lua

prosody xmpp server ports

  • 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.

prosody-enable-bosh-xmpp-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.

prosody xmpp letsencrypt certbot

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.

prosody xmpp letsencrypt certbot

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:

prosody ssl virtual host

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.

prosody-xmpp-ubuntu

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

install prosody ubuntu 18.04

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.

prosody xmpp bosh setup

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 🙂

Rate this tutorial
[Total: 4 Average: 4.8]

4 Responses to “How to Set Up Prosody XMPP Server on Ubuntu 22.04

  • MrAdminus
    4 years ago

    Hi Linuxbabe
    I seldom comment, know you’re busy, however I just wanted to say that I really appreciate your work.
    You’re really smart and I like the way you explain things, it’s very easy to follow.
    I’ve learned many things from you.
    So I guess I just wanted to say thanks and keep up the good work!

  • Another useful guide. I ran into one slight challenge and had to amend rights to the following file to remove a log file error.
    /etc/prosody/certs/localhost.key
    with the following code –

     chmod o+r localhost.key 

    however I suspect that this was less a disabling issue I thought it was just confusing the other error message I think I was having with the chat client I was using.

    One request is that I am not getting push messages on an iOS client, (using chat secure) and need to work on that – so a guide extension here may be useful.

    Thanks again

  • Hello, I have already installed Jitsi on my ubuntu server following this guidline https://www.digitalocean.com/community/tutorials/how-to-install-jitsi-meet-on-ubuntu-20-04 (works fine) and now I need to install/configure my XMPP service on the same server. Since Prosody is already installed how I could configure everything not impacting my Jitsi set up? Thank you.

Leave a Comment

  • Comments with links are moderated by admin before published.
  • Your email address will not be published.
  • Use <pre> ... </pre> HTML tag to quote the output from your terminal/console.
  • Please use the community (https://community.linuxbabe.com) for questions unrelated to this article.
  • I don't have time to answer every question. Making a donation would incentivize me to spend more time answering questions.

The maximum upload file size: 2 MB. You can upload: image. Links to YouTube, Facebook, Twitter and other services inserted in the comment text will be automatically embedded. Drop file here