Instant Messageing

Prosody Logo

Prosody IM is a lightweight and relatively easy to use XMPP instant messageing server.


IP Addresses


In this document we use example IP addresses. Note that none of these will work in real situations.

Add dedicated IPv4 and IPv6 addresses for XMPP on the server:

$ sudo ip addr add dev eth0
$ sudo ip addr add 2001:db8::35/64 dev eth0

Also add them to the file /etc/network/interfaces to make them persistent across system restarts:

iface eth0 inet static
iface eth0 inet6 static
    address 2001:db8::35/64

See Network.


The following public DNS host (A and AAAA) records are needed:

  • IPv4 host record (A) for pointing to your (dynamic) public IP address.
  • IPv6 host record (AAAA) for pointing to the dedicated IPv6 address.

Any file-transfer proxy servers need host records too.

Name Type Content Priority TTL
xmpp A   300
xmpp AAAA 2001:db8:face::35    

Check the “Add also reverse record” when adding the first IPv6 entry.

Additional services (or components, as they are frequently called) like “conference” above can be added as sub-domain records. This is needed for XMPP users outside of your domain to be able to use these services:

Name Type Content Priority TTL
conference CNAME    
proxy CNAME    

To inform clients and other domains servers, how to connect to our domain, the following service records (SRV) are added:

Name Type Content Priority TTL
_xmpp-client._tcp SRV 5 5222    
_xmpp-server._tcp SRV 5 5269    
_xmpp-server._tcp.conference SRV 5 5269    

Provide an alternative connection method over HTTPS.

Name Type Content Priority TTL
_xmppconnect TXT _xmpp-client-xbosh=    

TLSA (DANE) records allow connecting clients and servers to verify the TLS certificates of our server:

Name Type Content
_5222._tcp.xmpp TLSA 3 0 1 f8df4b2e………………………….76a2a0e5
_5269._tcp.xmpp TLSA 3 0 1 f8df4b2e………………………….76a2a0e5
_5281._tcp.xmpp TLSA 3 0 1 f8df4b2e………………………….76a2a0e5


The XMPP daemons listen on TCP ports 5222, 5269 and 5281 for incoming connections.

IPv4 NAT port forwarding:

Protocol Port No. Forward To Description
TCP 5000 XMPP file transfers proxy
TCP 5222 XMPP client connections
TCP 5269 XMPP server connections
TCP 5281 XMPP BOSH client connections

Allowed IPv6 connections:

Protocol Port No. Destination Description
TCP 5000 2001:db8:face::35 XMPP file transfers proxy
TCP 5222 2001:db8:face::35 XMPP client connections
TCP 5269 2001:db8:face::35 XMPP server connections
TCP 5281 2001:db8:face::35 XMPP BOSH client connections

Software Package Repository

Ubuntu 14.04 ‘Trusty Thar’ has currently included Prosody 0.9.1 in its package repository.

The latest version as of May 2014 is 0.9.4. Notable immprovements for security and encryption where introduced in version 0.9.2.

Therefore using the projects own package repository is recommended.

Add these software repositories to the systems package list:

$ sudo -s
 echo "deb `lsb_release -sc` main" \
    > /etc/apt/sources.list.d/
$ echo "deb-src `lsb_release -sc` main" \
    >> /etc/apt/sources.list.d/
$ exit

All software packages released by the project are signed with its own GPG key.

Add the signing key to the systems trusted keyring:

$ wget -O - | sudo apt-key add -

Update the systems packages list:

$ sudo apt-get update



Unfortunately there is one outdated LUA library in the Ubuntu package repository which we need to get from another source: LuaExpat.

We use LuaRocks, the package manager for Lua modules, to help us with download and installation of LuaExpat.

So first we have to install LuaRocks. LuaRocks is also available from the Ubuntu package repository, but outdated as well.

So here is how we download and install LuaRocks from its sources:

$ sudo apt-get update
$ sudo apt-get install build-essential liblua5.1-0-dev libreadline-dev
$ cd /usr/local/src/
$ wget
$ tar -xzf luarocks-2.2.2.tar.gz
$ cd luarocks-2.2.2
$ ./configure
$ make build
$ sudo make install bootstrap

Now we can install the LuaExpat package using Luarocks:

$ sudo luarocks install luaexpat


Another Lua library we install separetly is the Lua bitop fast bit manipulation library. It will be needed by the community-module http_upload added later, therefore the prosody package installation does not know we need it, and won’t install it automatically:

$ sudo apt-get install lua-bitop

Prosody Installation

Finally we install the Prosody package:

$ sudo apt-get install prosody

After installation we have on our server:

  • The user and group prosody which will run the server;
  • The group ssl-cert, with the user prosody added as member;
  • The directory /etc/ssl/private and the key-file /etc/ssl/private/ssl-cert-snakeoil.key have its group ownership changed to ssl-cert and group read access-rights added;
  • A directory structure for configuration files in /etc/prosody;
  • A system service prosody is created and started;

Third-party server modules

A community repository of modules exists at the prosody-modules project.

The easiest way to fetch and install these is currently via Mercurial ( hg ). Once you have it installed, simply run:

$ sudo mkdir /usr/local/lib/prosody
$ hg clone /usr/local/lib/prosody/modules

Since this are mostly under heavy development, you need to update them from time to time:

$ cd /usr/local/lib/prosody/modules
$ sudo hg pull --update
$ sudo prosodyctl restart

Web Template

A bootstrap theme for the user registration website:

$ sudo mkdir -p /usr/local/lib/prosody/register-templates
$ cd /usr/local/lib/prosody/register-templates/
$ sudo git clone


See Configuring Prosody on the Prosody website.

All configuration files are in the /etc/prosody directory.

IP Addresses

---------- Server-wide settings ----------
-- Settings in this section apply to the whole server and are the default settings
-- for any virtual hosts

 -- Listen on dedicated IP address of only
 interfaces = { "", "2001:db8::35" }

Additional Modules

-- These paths are searched in the order specified, and before the default path
plugin_paths = { "/usr/local/lib/prosody/modules" }
    -- Community modules
        "blocking"; -- XEP-0191: Allows the client to manage a simple list of blocked JIDs, requires "privacy" module
        "smacks"; -- XEP-0198: Reliability and fast reconnects for XMPP
        "carbons"; -- XEP-0280: Message Carbons, allows users to maintain a shared and synchronized view of all conversations across all their online clients and devices.
        "mam"; -- XEP-0313: Message Archive Management.
        "csi"; -- XEP-0352: Client State Indication
        "throttle_presence"; -- Cut down on presence traffic when clients indicate they are inactive (using the CSI protocol).
        "register_web"; -- A web interface to register user accounts.

Registration Website Template

Change the layout of the ugly mod_register_web plug-in from Prosody:

register_web_template = "/usr/local/lib/prosody/register-templates/Prosody-Web-Registration-Theme";


-- This is a (by default, empty) list of accounts that are admins
-- for the server. Note that you must create the accounts separately
-- (see for info)
-- Example: admins = { "", "" }
admins = { "" }

Certificate and Key

Prosody must be able to read the protected key file:

$ sudo chgrp ssl-cert /etc/ssl/private/

Certificate and private key for TLS authentication and encryption and enforce our selected Cipher Suite Selection:

-- SSL/TLS-related settings.
ssl = {
    options = {
    ciphers = "kEDH+aRSA+AES128:kEECDH+aRSA+AES128:+SSLv3";
    dhparam = "/etc/ssl/dhparams/dh_4096.pem";
    key = "/etc/ssl/certs/";
    certificate = "/etc/ssl/certs/";

Force clients to use TLS encrypted connections:

-- Force clients to use encrypted connections? This option will
-- prevent clients from authenticating unless they are using encryption.
c2s_require_encryption = true

Virtual Host

Create a new virtual host configuration file /etc/prosody/conf.d/

-- Prosody XMPP virtual host
VirtualHost ""

    -- Assign this host a certificate for TLS, otherwise it would use the one
    -- set in the global section (if any).
    ssl = {
        key = "/etc/ssl/private/";
        certificate = "/etc/ssl/certs/";

    -- Components

    --- Set up a MUC (multi-user chat) room server on
    --- Also needs SRV record in DNS pointing to the XMMP server host and port.
    Component "" "muc"

    -- Set up a SOCKS5 bytestream proxy for server-proxied file transfers:
    --- Also needs host record (A and AAAA) the XMMP IP address.
    Component "" "proxy65"
        modules_enabled = {

Tor Hidden Service

Add a Tor Hidden Service by editing /etc/tor/torrc:

# Prosody XMPP Hidden Service for
HiddenServiceDir /var/lib/tor/hidden_services/xmpp-server
HiddenServicePort 5000
HiddenServicePort 5222
HiddenServicePort 5269
HiddenServicePort 5280
HiddenServicePort 5281

Reload the Tor client:

$ sudo service tor reload

Read the newly generated *.onion hostname:

$ sudo cat /var/lib/tor/hidden_services/xmpp-server/hostname

Create a new virtual host configuration file /etc/prosody/conf.d/duskgytldkxiuqc6.onion.cfg.lua:

-- Prosody XMPP Tor hidden server duskgytldkxiuqc6.onion
VirtualHost "duskgytldkxiuqc6.onion"

    -- Assign this host a certificate for TLS, otherwise it would use the one
    -- set in the global section (if any).
    ssl = {
        key = "/etc/ssl/private/";
        certificate = "/etc/ssl/certs/";

    -- Components

    --- Set up a MUC (multi-user chat) room server on
    --- Also needs SRV record in DNS pointing to the XMMP server host and port.
    Component "conference.duskgytldkxiuqc6.onion" "muc"

    -- Set up a SOCKS5 bytestream proxy for server-proxied file transfers:
    --- Also needs host record (A and AAAA) the XMMP IP address.
    Component "proxy.duskgytldkxiuqc6.onion" "proxy65"

Prosody Onions-Map

mod_onions is a Prosody Plugin to interconnect XMPP servers trough Tor by mapping tor hidden service addresses to XMPP server names.

The map file is maintened on GitHub

To install the map file:

$ cd /usr/local/lib/prosody
$ sudo sudo git clone

To make prosody use the map file, reference it in the main configuration file /etc/prosody/prosody.cfg.lua as follows:

-- Override the address used to connect to a given host with the address of
-- a hidden service.
Include "/usr/local/lib/prosody/xmpp-onion-map/onions-map.lua"

To update the map file periodically and reload the module:

$ cd /usr/local/lib/prosody
$ sudo git remote update
$ sudo git pull
$ sudo prosodyctl restart
$ telnet localhost 5582
Trying ::1...
Connected to localhost.
Escape character is '^]'.
|                    ____                \   /     _
                    |  _ \ _ __ ___  ___  _-_   __| |_   _
                    | |_) | '__/ _ \/ __|/ _ \ / _` | | | |
                    |  __/| | | (_) \__ \ |_| | (_| | |_| |
                    |_|   |_|  \___/|___/\___/ \__,_|\__, |
                    A study in simplicity            |___/

| Welcome to the Prosody administration console. For a list of commands, type: help
| You may find more help on using this console in our online documentation at

| Reloaded on
| Reloaded on
| Reloaded on localhost
| OK: Module reloaded on 3 hosts

Configuration Syntax Check

$ sudo luac -p /etc/prosody/prosody.cfg.lua

If there is no output there are no syntax errors. Otherwise filename and line-number are shown along with a error message.

Restart Server

$ sudo service prosody restart

Add Users

See Creating Accounts on the Prosody website.

$ sudo prosodyctl adduser <username>
Enter new password: ********
Retype new password: ********



Write how to log and monitor.

Online Security Test

On the website users and server administrators can inspect the security of their XMPP servers.

Backup Considerations


Write which data to backup for Prosody with ninjabackup.