homebrewserver.club/content/instant-messaging/configuring_an_xmpp_server_prosody_0.11.md

Title: Configuring an XMPP server for secure, mobile instant messaging
Date: 2018-11-17
Tags: xmpp, chat, guide, instant messaging, prosody
Slug: configuring-a-modern-xmpp-server
Summary: Hands-on step-by-step guide that shows how to set up a federated chat server based on Prosody 0.11 configured for security, mobile messaging, rich features and ease of use.

[TOC]

Introduction
---

This is a guide to set up a modern XMPP server focused on security and mobile messaging. The whole guide assumes Debian stable running on the server, the fact that you will end up hosting a few of your friends and that you have some basic skills working on a linux command line.

Please note that if you've followed this guide in the past you might need to have a look at [the update considerations](#attention-upgrading-from-previous-versions)

Set up firewall and DNS
----

To make your server communicate make sure following ports are open in your firewall:

    :::console
    5000 (for proxying large file transfers between clients)
    5222 (for client to server)
    5269 (server to server)
    5281 (default https port for prosody)

Additionally make sure you have set up a domain name and have A-records for the following subdomains:

    :::console
    groups.myserver.org (for the groupchats)
    upload.myserver.org (for the HTTP-Upload component)
    proxy.myserver.org (for the file transfer proxy)

This guide uses the ones above but feel free to come up with more creative subdomains :)

Enabling HTTPS
---

First we acquire a signed HTTPS-certificate via [Let's Encrypt](https://letsencrypt.org/):
This is among others required for Gajim plugins to work properly; self-generated certs will not work.

Install Certbot and get new certificates for your domain (replace myserver.org with your own):

    :::console
    sudo apt-get update && sudo apt-get install certbot
    certbot certonly -d myserver.org
    certbot certonly -d groups.myserver.org
    certbot certonly -d upload.myserver.org
    certbot certonly -d proxy.myserver.org

Pick an authentication method that [best fits your situation](https://certbot.eff.org/docs/using.html#getting-certificates-and-choosing-plugins). If you don't have a webserver running, using the 'standalone' option works well.

Should you succeed, you will be able to read something like:

    :::console
    - Congratulations! Your certificate and chain have been saved at
     /etc/letsencrypt/live/myserver.org/fullchain.pem. Your
     cert will expire on 2019-02-15. To obtain a new or tweaked version
     of this certificate in the future, simply run certbot again. To
     non-interactively renew *all* of your certificates, run "certbot
     renew"


Installing and configuring Prosody, the XMPP server
---

Install the newest version of Prosody and its dependencies from the official prosody repository:

    :::console
    echo deb http://packages.prosody.im/debian $(lsb_release -sc) main | sudo tee -a /etc/apt/sources.list

    wget https://prosody.im/files/prosody-debian-packages.key -O- | sudo apt-key add -

    sudo apt-get update && sudo apt-get install prosody lua-sec

Install the newest prosody plugins:

    :::console
    apt-get install mercurial
    cd /usr/src
    hg clone https://hg.prosody.im/prosody-modules/ prosody-modules


Make a backup of the default prosody configuration and install [the one by the homebrewserver.club](https://homebrewserver.club/downloads/prosody.0.11.cfg.lua)

    :::console
    cd /etc/prosody
    cp prosody.cfg.lua prosody.cfg.lua.original
    wget https://homebrewserver.club/downloads/prosody.0.11.cfg.lua -O prosody.cfg.lua

The homebrewserver.club prosody config
---

    :::console
    -- a custom prosody config focused on high security and ease of use across (mobile) clients
    -- provided to you by the homebrewserver.club
    -- the original config file (prosody.cfg.lua.original) will have more information

    plugin_paths = { "/usr/src/prosody-modules" } -- non-standard plugin path so we can keep them up to date with mercurial

	modules_enabled = {
	                "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
	                "private"; -- Private XML storage (for room bookmarks, etc.)
	                "vcard4"; -- User Profiles (stored in PEP)
	                "vcard_legacy"; -- Conversion between legacy vCard and PEP Avatar, vcard
                    "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
	                "register"; --Allows clients to register an account on your server
	                "pep"; -- Enables users to publish their mood, activity, playing music and more
	                "carbons"; -- XEP-0280: Message Carbons, synchronize messages accross devices
	                "smacks"; -- XEP-0198: Stream Management, keep chatting even when the network drops for a few seconds
	                "mam"; -- XEP-0313: Message Archive Management, allows to retrieve chat history from server
	                "csi_simple"; -- XEP-0352: Client State Indication
	                "admin_adhoc"; -- Allows administration via an XMPP client that supports ad-hoc commands
	                "blocklist"; -- XEP-0191  blocking of users
                    "bookmarks"; -- Synchronize currently joined groupchat between different clients.
	                --"cloud_notify"; -- Support for XEP-0357 Push Notifications for compatibility with ChatSecure/iOS.
	                -- iOS typically end the connection when an app runs in the background and requires use of Apple's Push servers to wake up and receive a message. Enabling this module allows your server to do that for your contacts on iOS.
	                -- However we leave it commented out as it is another example of vertically integrated cloud platforms at odds with federation, with all the meta-data-based surveillance consequences that that might have.
                    "server_contact_info"; --add contact info in the case of issues with the server
                	};

    allow_registration = false; -- Enable to allow people to register accounts on your server from their clients, for more information see http://prosody.im/doc/creating_accounts

    certificates = "/etc/prosody/certs"
    https_certificate = "certs/uploads.myserver.org.crt"

    c2s_require_encryption = true -- Force clients to use encrypted connections

    -- Force certificate authentication for server-to-server connections?
    -- This provides ideal security, but requires servers you communicate
    -- with to support encryption AND present valid, trusted certificates.
    -- NOTE: Your version of LuaSec must support certificate verification!
    -- For more information see http://prosody.im/doc/s2s#security

    s2s_secure_auth = true

    pidfile = "/var/run/prosody/prosody.pid"

    authentication = "internal_hashed"

    -- Archiving
    -- If mod_mam is enabled, Prosody will store a copy of every message. This
    -- is used to synchronize conversations between multiple clients, even if
    -- they are offline. This setting controls how long Prosody will keep
    -- messages in the archive before removing them.

    archive_expires_after = "1w" -- Remove archived messages after 1 week

    disco_items = { -- allows clients to find the capabilities of your server
        {"upload.myserver.org", "file uploads"};
        {"groups.myserver.org", "group chats"};
    }

    log = { --disable for extra privacy
        info = "/var/log/prosody/prosody.log"; -- Change 'info' to 'debug' for verbose logging
        error = "/var/log/prosody/prosody.err";
        "*syslog";
    }

    VirtualHost "myserver.org"

    -- Enable http_upload to allow image sharing across multiple devices and clients
    Component "upload.myserver.org" "http_upload"

    -- Enable groupchats on your server
    Component "groups.myserver.org" "muc"
    modules_enabled = { "muc_mam", "vcard_muc" } --enable archives and avatars for groupchats

    -- Set up a file transfer proxy to facilitate clients sending larger files to each other
    Component "proxy.myserver.org" "proxy65"


Replace all instances of the placeholder domain name with `yourdomain` in the config file with your own:

    :::console
    sed -i 's/myserver.org/yourdomain/g' prosody.cfg.lua

Alternatively you can change them by hand. They are on lines 70, 81, 84, 88, 91 of prosody.cfg.lua

Make Prosody import the LetsEncrypt certificates:

    :::console
    prosodyctl --root cert import /etc/letsencrypt/live

You might get the following output:

    :::console
    Imported certificate and key for hosts myserver.org, groups.myserver.org, uploads.myserver.org, proxy.myserver.org

However, no need to worry since the last certificate contains information for all the above subdomains.

Finishing up
---

Add an entry to cron to automatically renew LetsEncrypt certificates

    :::console
    sudo crontab -e

And add:

    :::console
    0 4 0 * 0  /usr/bin/certbot renew --renew-hook "prosodyctl --root cert import /etc/letsencrypt/live" --quiet

This will check and renew the certificates every week on sunday at 04:00.

After you've set up all of the above it is time to start the server:

    :::console
    /etc/init.d/prosody restart

Users can be added from the command line, you will also be prompted for a password:

    :::console
    prosodyctl adduser me@myserver.org

Alternatively you can change `allow_registration = false;` to `allow_registration = true;` in the config (line 35) to allow users to register accounts on your server via their clients.

Now you can try connecting to your own server by using a client like Gajim or Conversations. Login with the above configured username and password.

If you have questions about Prosody, the project's [documentation](http://prosody.im/doc) is quite good. If you can't find answers there, try contacting prosody developers and users directly via [the Prosody XMPP chatroom](xmpp:prosody.conference.prosody.im?join)

This guide is a companion to our article [Have You Considered The Alternative?](http://homebrewserver.club/have-you-considered-the-alternative.html) on instant messaging. Also check out our guide on [XMPP clients](http://homebrewserver.club/picking-modern-xmpp-clients.html).

Attention: Upgrading From Previous Versions
---

Previous versions of this guide[^1] included instructions how to set up a MySQL/MariaDB database back-end. That is because earlier versions of prosody had SQL as a dependency for message archiving. This is no longer the case. The new guide is lighter and leaves out MySQL/MariaDB in favor of the inbuilt file-based storage. This should be sufficient for hundreds of users.

When upgrading to prosody 0.11 on a server using sql make sure to run database upgrades with:

    :::console
    prosodyctl mod_storage_sql upgrade


[^1]: Previous articles descibed how to set up [Prosody 0.9](https://homebrewserver.club/drafts/configuring-a-modern-xmpp-server-0.9.html) and [Prosody 0.10](https://homebrewserver.club/drafts/configuring-a-modern-xmpp-server-0.10.html)