Quick-wiki: Prosody

October 3, 2021

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.

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

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:

chgrp to prosody for certs.
chmod 0640 on private keys, if required.
merge certs into single pem file by

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

repeat step 2 and 3 on newly generated file.

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.

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.