Set Up Prosody

July 6, 2018 ยท 6 minute read

Posted in: computing unix prosody conversations xmpp im chat

What is Prosody?

Prosody IM Server logo

Prosody is an XMPP server; for most people and most uses, that means it’s an instant messaging server that anyone can run, and talk to anyone with an account on any other XMPP server. So unlike centralized chat platforms like WhatsApp or Facebook Messenger, you don’t have to trust a single big company to run it and to not misuse your data. I’m focusing on Prosody here because I run a Prosody server, and in my experience it’s easier to set up and run than others.

Conversations IM app logo

Conversations is an easy to use, but full-featured XMPP client (chat app) for Android, which adds a lot of capabilities that older clients haven’t had. It has all the features you’d expect from a mobile messaging application, like message history, sending images, videos, etc., low battery use, multi-user chat rooms, and simple end-to-end encryption. This is great. It means there’s a federated end-to-end encrypted messenger that is as easy and fun to use as Signal or WhatsApp.

The not-so-great: XMPP is a modular standard, which means that not every server and not every client will implement all of the same parts. Conversations, being a new client that offers a lot of new features, also makes a lot of demands on the server. There are a lot of modules (called XEPs) that it needs that most servers don’t implement, or don’t have turned on by default.

You don’t need to install your own XMPP server to use Conversations — just sign up on an existing one; they even provide a default. This guide is for if you want to run your own for yourself, your family, and your friends.

It’s not terribly hard to get Prosody to support all of these XEPs, but it does take a little bit of work and digging. I’m going to save you the digging part.


Installing Prosody

I’m not going to go over installing prosody on a Linux server. It’s probably available in your package manager; I installed it like this:

    dnf install prosody

Your system may use, e.g., apt-get or pacman to do the same thing.

You should refer to the Prosody setup docs for basic configuration. The main things you need to configure are the host you will be serving on, and your encryption certificates. Self-signed certificates may be good enough, but I’m using Let’s Encrypt.

Once you have Prosody set up basically, you will be able to connect with Conversations, and do basic chats, either one on one or multi-user. A lot of things won’t work, though, like OMEMO encryption, which is what you want to be using.

Enabling needed modules included with Prosody

The first step is enabling modules that are bundled with Prosody, but which aren’t enabled by default.

You’ll need to look in your /etc/prosody/prosody.cfg.lua (or wherever your config file was installed).

The defaults look like this on Fedora; they may be different on your system. Double hyphens are comments.

-- This is the list of modules Prosody will load on startup.
-- It looks for mod_modulename.lua in the plugins folder, so make sure that exists too.
-- Documentation on modules can be found at:
modules_enabled = {

        -- Generally required
                "roster"; -- Allow users to have a roster. Recommended ;)
                "saslauth"; -- Authentication for clients and servers. Recommended if you want to log in.
                "tls"; -- Add support for secure TLS on c2s/s2s connections
                "dialback"; -- s2s dialback support
                "disco"; -- Service discovery

        -- Not essential, but recommended
                "private"; -- Private XML storage (for room bookmarks, etc.)
                "vcard"; -- Allow users to set vCards
        -- These are commented by default as they have a performance impact
                --"privacy"; -- Support privacy lists
                 --"compression"; -- Stream compression (Note: Requires installed lua-zlib RPM package)

        -- Nice to have
                "version"; -- Replies to server version requests
                "uptime"; -- Report how long server has been running
                "time"; -- Let others know the time here on this server
                "ping"; -- Replies to XMPP pings with pongs
                "pep"; -- Enables users to publish their mood, activity, playing music and more
                "register"; -- Allow users to register on this server using a client and change passwords

        -- Admin interfaces
                "admin_adhoc"; -- Allows administration via an XMPP client that supports ad-hoc commands
                --"admin_telnet"; -- Opens telnet console interface on localhost port 5582
        -- HTTP modules
                --"bosh"; -- Enable BOSH clients, aka "Jabber over HTTP"
                --"http_files"; -- Serve static files from a directory over HTTP

        -- Other specific functionality
                "posix"; -- POSIX functionality, sends server to background, enables syslog, etc.
                --"groups"; -- Shared roster support
                --"announce"; -- Send announcement to all online users
                --"welcome"; -- Welcome users who register accounts
                --"watchregistrations"; -- Alert admins of registrations
                --"motd"; -- Send a message to users when they log in
                --"legacyauth"; -- Legacy authentication. Only used by some old clients and bots.

You’ll want to add these to that section:

-- locally needed

This gets you a lot of the way there. At this point, most things in Conversations will work, including OMEMO encryption, and message syncing between devices. Offline delivery will work sort of, but you may see oddities like duplicate messages.

Getting and installing additional modules

The remaining modules you need are included in a community repository. You’ll have to use Mercurial to clone the repository.

The repository includes a bunch of directories named mod_something. You can
copy each of the ones you need (the whole directory) to the Prosody modules
directory. On my system, it's `/usr/lib64/prosody/modules/`. The
ones you need, and how to add them to the same list of modules as above, is

– locally needed “carbons”; “mam”; “smacks”; “smacks_noerror”; “cloud_notify”; “csi”; “blocking”; “http_upload”; “omemo_all_access”; ```


Conversations has, under your account info, a menu toggle to show server information. If you’ve set everything up correctly, it will look like this:

List of server functions available to Conversations

If not everything is checked, you should go back over the list of modules and make sure that you’ve installed all the modules you need.

One widespread criticism of XMPP/Jabber and an excuse for its lack of wider adoption is that there are too many modules to the standard to guarantee compatibility between clients and servers. But it doesn’t have to be so hard. You can take Conversations’ requirements as the baseline for what an XMPP server needs to support in 2018, and make sure your server supports those things.

Many thanks to everyone working on Conversations and Prosody, including those working on the Prosody community modules.

Share on Mastodon | Follow on Mastodon