Quick-wiki: Prosody

Last update: 10/2021, Prosody v11.9-2 from Debian.

This is a WIP quick-wiki for quick reference for Prosody, an XMPP server software and XMPP in general.

I do had an XMPP account from my diasp.in account, but things being up down sometimes and my urge to experiment and learn how prosody works got me into this installation. It’s a mess, but it’s super lightweight to run.

Table of Content


Installation and Configurations

Most of the initial setup was done by following DO’s ‘How To Install Prosody on Ubuntu 18.04’, on Debian machine with following changes:



Atleast two DNS A records needs to be added:

A third DNS record maybe required for uploads.

Prosody documentation mentions that by using SRV records, a user with XMPP address user@chat.example.org can use DNS redirection to use user@example.org address.

The following is the DNS configuration:

_xmpp-client._tcp.example.org. 18000 IN SRV 0 5 5222 chat.example.org.
_xmpp-server._tcp.example.org. 18000 IN SRV 0 5 5269 chat.example.org.

Though implementing shows following issue in prosody logs:

info    Incoming s2s stream example.com->example.org closed: This host does not serve example.org

Prosody modules

In prosody, most of the features are enabled via modules(plugins).

Debian has prosody-modules package, but it misses some community and early-stage modules. Fetched the modules from directly from prosody’s mercurial by:

  hg clone https://hg.prosody.im/prosody-modules/ prosody-modules

And adding path to plugin_paths variable in prosody conf.

To update modules

hg pull --update

Modules enabled

List of core modules with description.

List of prosody community modules with description.

A reload is required for adding or removing a module from configuration.


TLS certs are required for both main and MUC domain. For my present setup, the renewal needs to be done by stopping nginx, so that certbot can bind to port 80 and do the renewals. As of now the process is manual.

After renewal checklist:

sh -c 'cat privkey.pem fullchain.pem >key-and-cert.pem'

TODO: read more on this, if this is required anymore, or automate this. Presently using pre hook to stop nginx and post hook to make the combine file and restart nginx tumbles because nginx may not be able to reload in rapid succession due to multiple certs triggering pre and post scripts. Adding sleep in script may help. Another approach is to add nginx conf for it.


prosodyctl adduser user@chat.example.org
prosodyctl passwd user@chat.example.org
prosodyctl deluser user@chat.example.org

Debugging and logs

prosodyctl about
prosodyctl check

# for individual checks only
prosodyctl check {config|dns|certs}