Translation(s): English - Francais
This page provides information about the installation and configuration of Prosody, an [XMPP]/Jabber server on Debian. Prosody can be used for real-time communication using only open-source software - a range of compatible messaging apps are available for all desktop and mobile platforms.
Contents
The XMPP service will be offered on the host named example.org with TLS encryption.
Before starting make sure example.org actually points to the public IP of the host (cf. DNS records).
In addition, the port 5222 and 5269 are open to the public IP.
Installation of Prosody
Install the package:
apt install prosody
Configuration
Choosing a domain
Before you begin, you need a domain name that can be used. Any domain name will work, but note that it cannot be changed after user accounts are created (you would need to recreate all user accounts if you change the domain in your config).
We recommend not using a subdomain (e.g. use 'example.org' instead of 'xmpp.example.org') for the same reasons that your email address is not username@smtp.example.org, it is weird to have a chat address like username@xmpp.example.org. If you are unable to point your main domain name at the server running Prosody, you can use SRV records (which are similar to MX records in SMTP). Find more information in the official Prosody documentation on DNS.
Updating the default configuration
Configuration is done in the the config file at /etc/prosody/prosody.cfg.lua. The Prosody package follows the Debian convention of having conf.d/ and conf.avail/ directories. Any conf.d/*.cfg.lua files are included by the main config file, however using this method is entirely optional (the Prosody team considers it easier and clearer to simply have everything in the main prosody.cfg.lua).
You can read about the configuration file structure and syntax in the official Prosody configuration documentation. The default configuration is also well commented with useful information. You are encouraged to read it.
By default the configuration has two VirtualHost entries:
VirtualHost "localhost"
VirtualHost "example.com" (for example purposes only, disabled by default)
Add a VirtualHost with your domain name (you can remove the example ones). You must have at least one VirtualHost defined for Prosody to start successfully.
Checking the configuration
After editing the configuration, run this command to check for any problems:
prosodyctl check
This command is always eager to find problems, even if they may not actually be problems (it's just trying to be helpful!). For example, if your server is behind a NAT/firewall and the IP address is different to what is in DNS, it may warn you about that even if everything is working okay. To tweak this and other things about the checks, see the official prosodyctl documentation.
Certificates
Like all modern internet protocols, Prosody uses TLS to secure and encrypt connections. This means you must obtain certificates for any domains you specify as a VirtualHost.
Most people obtain certificates from Let's Encrypt, using clients such as certbot or dehydrated. Prosody has support for easily importing certificates from these without any extra configuration. For more information, see the official Prosody documentation on Let's Encrypt.
For a standard certbot installation, you simply need to run this after your certificates are updated (or after you add a new VirtualHost):
prosodyctl --root cert import /etc/letsencrypt/live
certbot and most other tools have "deploy hooks" which can be used to automatically run commands after certificates are updated. However it won't hurt if you just simply run this daily, via cron or systemd timers.
For more advanced setups, refer to the official Prosody documentation on certificates.
Group chats
To allow group chats, you need to add a MUC (Multi-User Chat) component. Don't worry, this is simple to do and there is an example in the default config.
Component "groups.example.org" "muc"
modules_enabled = {
"mam_muc";
};The component domain should be a direct subdomain of your VirtualHost so that clients can easily discover it (the name of the subdomain can be anything you choose).
Group chats will work for your users even if you don't add a DNS record or certificate for your group chat domain. However it is recommended to add these so that you can invite users from other servers to join your chats.
You can read more in the official Prosody documentation on components.
File sharing
Another component you will likely want to set up is a HTTP file sharing service, which allows users to upload files so they can be shared in group chats or to send files to contacts who are not currently online. The upload service is authenticated, and for safety and security reasons, upload functionality is only available to user accounts on your Prosody instance.
All this is automatically handled by modern XMPP apps, all you need to do is configure the server side of things:
Component "share.example.org" "http_file_share"
No additional configuration is required if these things are all true:
- There is a DNS record for the component domain you chose, and it has DNS records (A/AAAA) that point to your Prosody server - Prosody has a certificate for share.example.com - Port 5281 is open in your firewall
However, everyone has different preferences and web setups, and if you want to tweak any of these things (e.g. change the port, or have requests go via a reverse proxy), you can. Just make sure you inform Prosody by updating your configuration. You can find all the necessary info in the official Prosody documentation for mod_http_file_share.
Create users (single)
Prosody is ready to create user accounts right out of the box. For this you can use prosodyctl:
prosodyctl adduser romeo@example.org
If you want to integrate Prosody with existing user accounts (such as LDAP), see the official Prosody documentation on authentication providers.
Additional modules
As of Debian 12 (bookworm) Prosody includes almost everything you want right out of the box. However some specific functionality needs extra modules, which are "community maintained". A selection of these extra modules are available in Debian via the prosody-modules package:
apt install prosody-modules
Documentation on these modules can be found at modules.prosody.im. Note that the online documentation is always for the latest module version, which may be newer than the version in Debian.
Push notifications
The most notable feature missing from a default Prosody installation in Debian 12 is push notifications. These are required if you have users of mobile clients on proprietary platforms such as iOS and (Google) Android.
Enabling push notifications is very simple. After you have installed the prosody-modules package, just locate the modules_enabled setting in prosody.cfg.lua, and add a new entry for "cloud_notify":
modules_enabled = {
-- list of modules here --
"cloud_notify";
-- maybe more modules here --
}After modifying the config, check for any problems by running:
prosodyctl check config
Direct TLS on HTTPS port
This is entirely optional, but if you or your users commonly find themselves unable to connect to Prosody due to network restrictions (e.g. firewalls on corporate or public networks), it's possible to allow your Prosody instance to receive connections over port 443 which is usually used for web browsing, and therefore usually works.
You can find a guide about this at the xmpp.org wiki for XEP-0368 setup.
Troubleshooting
If things aren't working:
1. prosodyctl check 2. Check your logs (e.g. journalctl -u prosody) for errors 3. Ask for help!