From Gentoo Wiki
Jump to: navigation, search
This page is a work in progress by MalakymR (talk | contribs). Treat its contents with caution.

Work in progress for net-im/prosody


Prosody is a modern XMPP communication server. It aims to be easy to set up and configure, and efficient with system resources. Additionally, for developers it aims to be easy to extend and give a flexible system on which to rapidly develop added functionality, or prototype new protocols.


USE flags

USE flags for net-im/prosody Prosody is a modern XMPP communication server

libevent Use libevent for event handling
libressl Use dev-libs/libressl instead of dev-libs/openssl when applicable (see also the ssl useflag)
luajit Use dev-lang/luajit instead of dev-lang/lua (ineffective with USE=-lua)
mysql Add mySQL Database support
postgres Add support for the postgresql database
sqlite Add support for sqliteembedded sql database
ssl Add support for SSL/TLS connections (Secure Socket Layer / Transport Layer Security)
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
zlib Support for compressing XMPP streams with mod_compression


root #emerge --ask net-im/prosody



By default prosody will allow in-band registration, it is important we turn this off unless required, otherwise the server may be used as a spam relay.

FILE /etc/jabber/prosody.cfg.lua
allow_registration = false;
--VirtualHost "localhost"
VirtualHost ""
        -- enabled = false -- Remove this line to enable this host


root #/etc/init.d/prosody start
root #rc-update add prosody default

Adding Users

root #prosodyctl adduser username@domain.tld
Enter new password:
Retype new password:

Add a second user for testing

root #prosodyctl adduser username2

This will produce a working setup that will allow communication between clients on this server only. Unless SRV records are setup client software will require the hostname of the server i.e.

Client Software

There are many clients to choose from, with varying levels of support for XEP modules.

  • Conversations - Requires SSL so will not work until a certificate is installed (will work with selfsigned - to add details to main article prosodyctl cert generate
  • Xabber - Android
  • net-im/pidgin - GUI Windows/Linux/Android
  • - curses based
  • net-irc/xmpp-irssi - Addon for curses based net-irc/irssi

Client Notes

(to test these now we need to specify the host name which may not be in the basic configuration)

  • Conversations - "incompatible server" (client requires SSL, not very configurable)
  • xmpp-irssi - failed (doesnt support SRV - need manually specify host, to confirm manual host configuration)
  • xabber - works (+SRV, to confirm manual host configuration)
  • pidgin - works (+SRV, to confirm manual host configuration)


Default logs to /var/log/jabber/prosody .log and .err Possible to output to syslog by adding log={"*syslog"} (can be done global or per server)



c2s_ports - Ports on which to listen for client connections.

c2s_interfaces - Interface on which to listen for client connections. Defaults to default interfaces. Note: in 0.8 and older versions, this option is called 'c2s_interface' and only supports listening on a single interface.

c2s_timeout - Timeout unauthenticated client connections. Off by default, no timeout.

c2s_ports = { 5222, 5322 } -- Listen on 5322 as well as 5222

c2s_interfaces = { "", "::1" } -- Listen only on these interfaces


s2s_ports - Ports on which to listen for server-to-server connections. Default is { 5269 }

s2s_interfaces - Interface on which to listen for server-to-server connections. Defaults to default interfaces. Note: in 0.8 and older versions, this option is called 's2s_interface' and only supports listening on a single interface.

s2s_timeout - Timeout for unauthenticated server connections. Default is 90 seconds.

SSL/TLS via LetsEncrypt

-LetsEncrypt/certbot for ssl c2s then s2s emerge --ask app-crypt/certbot (unmask ~amd64 for various packages) LE doesn't have a plugin to handle the certificates directly like it does with apache/nginx (yet... if someone writes one?)

We have three ways to request


hosts its own webserver under 443(or 80) for machines without a webserver (likely if your server is used for prosody only)

-your firewall/port redirection needs to be set for your public ip -since we only have 5 requests every 7 days - we should ideally setup the automated config to pick the options first

  1. one line request (to be scheduled later)

certbot certonly --standalone --preferred-challenges http --agree-tos -d xmpp.domain.tld -m youremail@whateverdomain.tld

- Congratulations! Your certificate and chain have been saved at
  /etc/letsencrypt/live/yourhostname.yourdomainname.tld/fullchain.pem. Your cert will
  expire on YYYY-MM-DD. 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


to automate this you would need to have access to your dns records on a nameserver which isn't often the case (ie. usually with your domain registrar) automation is not assumed so a hook is needed to push the TXT record before resuming


if you already have a webserver running this will simply use a folder in your current root to general the request - usually .well-known/acme-challenge/your-generated-key

Certificates are stored in /etc/letsencrypt/archive/sub.domain.tld/ though are symlinked to /etc/letsencrypt/live/sub.domain.tld/ ls -lha /etc/letsencrypt/live/

The certs are root:root by default - our server runs under jabber:jabber

-Add a group ssl-cert and apply is to folders/users groupadd ssl-cert usermod -a -G ssl-cert jabber (this needs to be run after every certificate update) chgrp -R ssl-cert /etc/letsencrypt chmod -R g=rX /etc/letsencrypt

(possible chmod 2755 /etc/letsencrypt to inherit permissions)

FILE /etc/jabber/prosody.cfg.lua
VirtualHost "yourdomain.tld"
        -- enabled = false -- Remove this line to enable this host
        ssl = {
                key = "/etc/letsencrypt/live/yourdomain.tld/privkey.pem";
                certificate = "/etc/letsencrypt/live/yourdomain.tld/fullchain.pem";

-example to add stronger encryption

-example from's website (lets change sudo to su as it already exists - jabber wont allow this logon though)

 sudo chmod 600 /path/to/certificate.key
 sudo chown jabber:jabber /path/to/certificate.key
 sudo -u jabber cat /path/to/certificate.key # Should succeed
 sudo -u nobody cat /path/to/certificate.key # Should fail

SRV Configuration

SRV records are the modern equivalent of MX records, but can be used for anything either standardised or not.

Servers aren't always located under domain.tld, and instead may be xmpp.domain.tld. So we do not need to log in as username@xmpp.domain.tld we can use an SRV record to let us know where domain.tld is found. This can also be used to redirect many domains to the same server, set ports and priorities. (extra) Benefits allow updating server location without clients needing to update their configurations.

SRV support in clients isn't complete - some do, some don't.

ie. @domain0.tld => xmpp.domain.tld @domain1.tld => xmpp.domain.tld

To do this we need access to our nameserver to update DNS records.

XMPP uses two records, one for S2S communications and one for C2S (note: clarify what S2S and S2C is)

C2S: _xmpp-client._tcp.yourdomain.tld (note: this is your user facing domain not server) DNS ENTRY, TYPE, PRIORITY, TTL, TARGET _xmpp-client._tcp, SRV, 30, 0, 1 5222 xmpp.yourdomain.tld.

S2S: pending _xmpp-server._tcp.yourdomain.tld

SRV records (lookup test, mxtoolbox or alt)

(windows) nslookup -type=SRV _xmpp-client._tcp.yourdomain.tld (linux/host) host -t SRV _xmpp-client._tcp.yourdomain.tld (linux/dig) dig _xmpp-client._tcp.yourdomain.tld SRV

nb. TXT DNS entries may be used (but should be a fallback)


-LetsEncrypt (generally required for S2S) cert for non-root applications -

-S2S (separate SRV record required)

nslookup -type=SRV _xmpp-server._tcp.yourdomain.tld

-SOCKS5 bytestream (conversations doesn't seem to support this)

-Client software (web based, irssi-xmpp, conversations, pidgin - SRV support check)

-sqlite/mysql etc (flat files by default)

-libevent (not really required for smaller servers)

-in-band registration and admin notifications

-service as non-root user(should be jabber:jabber, just need to confirm)

-allow s2s with servers that wont encrypt (gmail, openfire)