Quick-wiki: Prosody

October 3, 2021

Last update: 01/2025, Prosody v0.12.5-1~bpo12+1 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.

RFCs

RFC 6120: XMPP Core.
RFC 6121: XMPP IM.

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:

python3-certbot-nginx instead of certbot from Ubuntu PPA.
prosody from Debian main.
port 5269 for s2s communication instead of 5322.

Ports

5222/tcp: For client connections.
5269/tcp: For server to server connections.
5280/tcp: Serving files through HTTP.
5281/tcp: Serving files through HTTPS.

DNS

Atleast two DNS A records needs to be added:

chat.example.org: main XMPP address.
groups.example.org: for multiuser chat (MUC).

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

roster: Allow users to have a roster/friend list.
saslauth: Authentication for clients and server.
tls: Add support for secure TLS on c2s/s2s connections.
dialback: s2s dialback support. Identity verification through DNS system before accepting new s2s traffic.
disco: Service discovery. Essentially allows clients to discover MUCs, file transfer or other services supported by the server.
carbons: Keep multiple clients/devices in sync.
pep: Enables users to publish their avatar, mood, activity, playing music and more.
private: Private XML storage (for room bookmarks, etc.).
blocklist: Allow users to block other users.
vcard4: User profiles (in PEP).
vcard_muc: To allow defining avatar for MUC rooms.
vcard_legacy: Conversion between legacy vCard and PEP avatar.
limits: Enable bandwidth limiting for XMPP connections, both c2s and s2s.
uptime: Server uptime.
ping: Replies to pings with pong. Helps client establish if they have a stable connection to server or not.
mam: Store messages in archive. Also used by carbons for client sync.
csi_simple: Mobile optimizations.
admin_adhoc: Admin through XMPP client. Gajim, Pidgin and others supports it, dino doesn’t I believe.
bosh: XMPP over HTTP, ie from browser clients. Also, helpful when client is behind firewalls.
http_files: Serve static files from a directory. Also, if chat is unencrypted, gives a public browser link like http://prosody.example:5280/files/ for files.
http_upload: Community module. For file uploading in chat. Says not to be added in module enabled, but seems to work anyhow, To be investigated: how file upload works in other implementations without a separate domain or with it.
posix: POSIX stuff.
groups: Shared roster support ie server side shared friend/contact list like spaces in matrix.
watchregistrations: To get notified on new registrations. People automatically see each other in contact list.
muc_mam: Room archives.
smacks: Stream management, allow a client to resume a disconnected session, and prevent message loss.
bookmarks2: This module fetches users’ bookmarks.
cloud_notify: It allows clients to register an “app server” which is notified about new messages while the user is offline, disconnected or the session is hibernated by mod_smacks.

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.

Certs

Wrote a blog post for certificate management for Prosody with Nginx and Certbot.

Accounts

Create a new user, a password entry prompt follows.

prosodyctl adduser user@chat.example.org

Change a user password, a password entry prompt follows.

prosodyctl passwd user@chat.example.org

Delete a user account.

prosodyctl deluser user@chat.example.org

Debugging and logs

See all prosody related information.

prosodyctl about

Check issues with full installation. Combination of checking configuration, DNS and certs.

prosodyctl check

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

Glossary

BOSH: Bidirectional-streams Over Synchronous HTTP.
c2s/C2S: client to server.
s2s/S2S: server to server.
Roster: contact list.
OMEMO: OMEMO Multi-End Message and Object Encryption. An extension to XMPP that allows encryption with the Signal Protocol.
MUC: Multi-User Chat.
MIX: Mediated Information eXchange. MIX is a potential successor to MUC. Specification.
JID: Jabber ID or XMPP address.
XEP: XMPP Protocol Extension. XMPP standards they’re.
XMPP: Extensible Messaging and Presence Protocol.
XSF: XMPP Standards Foundation.