hbsc_site/raw/configuring_an_xmpp_server_prosody_0.9.md

Title: Configuring an XMPP server for secure, mobile instant messaging
Date: 2017-3-07
Category: xmpp
Tags: xmpp, chat, guide, instant messaging, prosody
Slug: configuring-a-modern-xmpp-server
Description: Hands-on step-by-step guide that shows how to configure Prosody for security, mobile messaging and ease of use.

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.

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

    :::console
    5222 (for client to server)
    5269 (server to server)
    5280 (default http port for prosody)
    5281 (default https port for prosody)


Enabling HTTPS
---

First we acquire a signed HTTPS-certificate via Let's Encrypt:
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 muc.myserver.org -d dump.myserver.org -d myserver.org 

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 2017-02-13. To obtain a new or tweaked version of this       
    certificate in the future, simply run certbot-auto again. To                       
    non-interactively renew *all* of your certificates, run                               
    "certbot-auto renew" 

Take note of the path where the certificate is stored as we will use it later.

Installing and setting up MySQL as a storage back-end
---

First update your repositories and install MySQL

    :::console
    apt-get update && apt-get install mysql-server

Run mysql as the root user:

    :::console
    mysql -u root -p

In mysql:

    :::console
    mysql> create database prosody;
    mysql> show databases;

Result should  be something like:

    :::console
    +--------------------+
    | Database           |
    +--------------------+
    | information_schema |
    | mysql              |
    | performance_schema |
    | prosody            |
    +--------------------+

    4 rows in set (0.00 sec)

Create a database account for prosody

    :::console
    mysql> create user prosody;

Give the user prosody the rights to access the database, make sure to change the password and take note of it

    :::console
    mysql> grant all on prosody.* to 'prosody'@'localhost' identified by 'userPassword';

Exit mysql:

    :::console
    exit;

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 && apt-get install prosody lua-dbi-mysql lua-zlib

Add the Let's Encrypt Certificates to Prosody and make sure Prosody can use them

    :::console
    cp /etc/letsencrypt/live/myserver.org/*.pem /etc/prosody/certs/

Make sure the certificates are owned by prosody and legible only by root:

    :::console
    chown -R prosody:prosody /etc/prosody/
    chmod -R 700 /etc/prosody/certs/

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.cfg.lua)

    :::console
    cd /etc/prosody
    cp prosody.cfg.lua prosody.cfg.lua.original
    wget https://homebrewserver.club/downloads/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
                "posix"; -- POSIX functionality, sends server to background, enables syslog, etc.
                "private"; -- Private XML storage (for room bookmarks, etc.)
                "vcard"; -- Allow users to set vCards
                "compression"; -- Stream compression (requires the lua-zlib package installed)
                "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"; -- XEP-0352: Client State Indication
                "http"; -- mod_http needed for XEP-363
                "admin_adhoc"; -- Allows administration via an XMPP client that supports ad-hoc commands
                "blocking"; -- XEP-0198 blocking of users
                --"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. 
    };

    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

    -- These are the SSL/TLS-related settings. 
    ssl = {
            certificate = "/etc/prosody/certs/fullchain.pem";
            key = "/etc/prosody/certs/privkey.pem";
    }

    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 = false

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

    authentication = "internal_hashed"

    storage = "sql" 

    -- Make sure to change the password 
    sql = { driver = "MySQL", database = "prosody", username = "prosody", password = "userPassword", host = "localhost" }

    log = {
            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 "dump.myserver.org" "http_upload"

    ---Set up a MUC (multi-user chat) room server on conference.example.com:
    Component "muc.myserver.org" "muc"

    compression_level = 9



Replace all instances of the placeholder domain name and passwords in the config file with your own:

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

Alternatively you can change them by hand. They are on line 61, 69, 72, 75 of prosody.cfg.lua

Finishing up
---

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).  

**edit 10th of december 2017**
updated instructions for new debian stable