Prosody

Updated 28 September 2022

Prosody is a modern XMPP server that aims at easy setup and system productivity. Prosody also focuses on providing more scalability and flexibility to help developers quickly implement functionality or prototype new protocols. XMPP, formerly known as Jabber, is an open, XML-based, free to use protocol for instant messaging and almost real-time presence status.

Installing and configuring PostgreSQL

Install and configure PostgreSQL according to the manual. Replace the dbtest database with prosody, and the test user with prosody.

Installing and configuring Prosody

First install Prosody:

Configure Prosody for xmpp.example.org:

-- This is a (by default, empty) list of accounts that are admins
-- for the server. Note that you must create the accounts separately
-- (see https://prosody.im/doc/creating_accounts for info)
-- Example: admins = { "user1@example.com", "user2@example.net" }
admins = { "admin@xmpp.example.org" }

...
storage = "sql" -- Default is "internal"

-- For the "sql" backend, you can uncomment *one* of the below to configure:
--sql = { driver = "SQLite3", database = "prosody.sqlite" } -- Default. 'database' is the filename.
--sql = { driver = "MySQL", database = "prosody", username = "prosody", password = "secret", host = "localhost" }
sql = { driver = "PostgreSQL", database = "prosody", username = "prosody", password = "secret", host = "localhost" }

...

-- Location of directory to find certificates in (relative to main config file):
certificates = "/etc/letsencrypt/live/xmpp.example.org"

----------- Virtual hosts -----------
-- You need to add a VirtualHost entry for each domain you wish Prosody to serve.
-- Settings under each VirtualHost entry apply *only* to that host.

--VirtualHost "localhost"
-- Prosody requires at least one enabled VirtualHost to function. You can
-- safely remove or disable 'localhost' once you have added another.

VirtualHost "xmpp.example.org"

Getting the Let's Encrypt certificate

Obtain a certificate for the xmpp.example.org domain, according to the manual.

Starting Prosody

Start the Prosody daemon:

Add Prosody to autostart:

Managing accounts

To add an account named admin@xmpp.example.org, run:

WARNING:  there is already a transaction in progress
Enter new password: 
Retype new password:

To change the password for admin@xmpp.example.org~, run:

WARNING:  there is already a transaction in progress
Enter new password: 
Retype new password:

To delete account admin@xmpp.example.org, run:

Components

Components are additional services on the server that are available to software clients via the subdomains of the main server. Those may be conferences, user directories, gateways to other protocols, etc.

Prosody supports both internal (i.e. operating within the framework of a given Prosody server) and external components (complying to the XEP-0114 standard).

Adding conferences

In XMPP, a separate subdomain is usually allocated for conferences (or multiuser chats). To define ~muc.xmpp.example.org~~ as a conference domain, add the following lines to the configuration file:

Component "muc.xmpp.example.org" "muc"
    name = "Conferences"

Adding an external component

To add an external component, you must tell Prosody which address and password the component will use to connect to the server.

To do so, define the external component (matrix.xmpp.example.org) and its password (secret) at the end of the configuration file:

-- Global config section --
component_interface = "0.0.0.0"
...
Component "matrix.xmpp.example.org"
    component_secret = "secret"

DNS configuration

SRV records allow for transparent DNS-level redirection of XMPP services to other domains and ports. Suppose that you want your account addresses look like user@example.org, while the XMPP server would actually be on xmpp.example.org.

XMPP supports two types of SRV records: to be used by clients ('c2s') and to be used by other XMPP servers ('s2s').

To add xmpp.example.org as an XMPP domain example.org, add the following SRV entries to DNS:

_xmpp-client._tcp.example.org. 18000 IN SRV 0 5 5222 xmpp.example.org.
_xmpp-server._tcp.example.org. 18000 IN SRV 0 5 5269 xmpp.example.org.

5222 and 5269 are the ports used for connection by clients and servers respectively.

Note that the target domain must be an existing A record. This cannot be an IP address or a CNAME record.

For services on subdomains (such as conferences and other front-end components) to be visible on other servers, they also need SRV records.

For instance, to define muc.example.org as a conference service, add the corresponding SRV record to DNS:

_xmpp-server._tcp.muc.example.org. 18000 IN SRV 0 5 5269 xmpp.example.org.