Prosody

Prosody is a light-weight, easy to configure, XMPP server. XMPP is an open and extensible Internet protocol used for communications, presence, identification, authentication etc. It's a big part of the Semantic Web movement which is all about achieving the functionality we need using open standards instead of specific applications.

Configuration

The prosody configuration is in /etc/prosody with a similar style to Apache or Nginx where individual site's configuration each exist in their own file in the conf.avail sub-directory usually having a filename matching the domain name. Sites are then enabled by creating sym-links in the conf.d sub-directory pointing to the available sites.

Here's an example configuration file for a specific domain which is set up as a chatroom server starting with the familiar VirtualHost directive to indicate the domain that this configuration covers. If you're only hosting users and don't need to host any chatrooms, then only the VirtualHost and SSL (and possibly admins) directives are needed.

VirtualHost "example.com"

	-- this is only necessary if not using certs in /etc/prosody/certs
	ssl = { 
		key = "/var/www/ssl/le-latest/privkey.pem";
		certificate = "/var/www/ssl/le-latest/fullchain.pem";
	}

-- use an empty admins list to disable all remote administration functions
-- admins from any domain can be used here
admins = { "foo@example.com" }

Component "muc.example.com" "muc"
	name = "The example.com chatrooms server"
	allow_registration = false
	c2s_require_encryption = true
	s2s_require_encryption = true

	-- set admins for the room and ensure only they can create new rooms
	-- note that admins in the main scope do not apply here
	admins = { "foo@example.com" }
	restrict_room_creation = true

	modules_enabled = {
		"vcard_muc"
	}

Component "mucfiles.example.com" "http_upload"

SSL certificates

If using LetsEncrypt certificates, then you need to ensure that the private keys are readable by Prosody (they same thing applies when using them with other services like Exim and Dovecot too).

The configuration is far simpler if there is a pair of certificate files of the form /etc/prosody/certs/example.com.crt and /etc/prosody/certs/example.com.key, or in the case of pem format, a single directory containing the fullchain.pem and the privkey.pem is fine. If this method is used, the certs are handled automatically without any ssl directives being necessary in the configuration. In the case of a LetsEncrypt certificate covering many domains (which is pem format), each domain's certificate can be a single symlink pointing to the LetsEncrypt location containing the pem files for the multi-domain certificate. In our configuration these symlinks all link to /var/www/ssl/le-latest which is automatically updated to the current certificate files.

Note that for any services that rely on the http module such as http_upload above, you will need a certificate that uses the name of the service, in this case https (or https.crt and https.key if not using pem format).

For server-to-server communications to work (which is needed for when users from other servers wish to join a room), there must be a valid certificate defined for the MUC sub-domain as well. The main certificate specified in the virtual host container can be used without any specific settings in the MUC component as long as it's a wild-card certificate or it covers the sub-domain in it's alt-name field.

Modules

Prosody uses modules to extend its functionality and ships with many useful, some like roster, offline, pep, sasl, tls and register are loaded by default, and other need to be specifically included in the modules configuration directive.

There are also many community modules available which can be installed separately. We use card_muc which allows supporting clients to display avatars for chatrooms.

Users

Users are managed from the CLI with prosodyctl, or can be added from a client with sufficient capabilities such as Pidgin if you're using an administrator account. Users can also change their own passwords and other personal information if the client supports it.

prosodyctl adduser foo@example.com

Chatrooms

The domain of the chat server is the domain of the "muc" component as as defined in the config, in our case muc.xmpp.organicdesign.nz. Using the configuration above, administrators of the MUC component are able to create new rooms from within their client if it has sufficient capabilities such as Pidgin or Dino.

Chatrooms can use OMEMO if they are non-anonymous, which means that member's JIDs should be set to be viewable by anyone no just moderators. Rooms can be kept private by adding a password or making them members-only. Members are added to the room either from the server, or using a client with sufficient room configuration capabilities.

Setting up notifications via email of offline messages

Todo

Using the Prosody server that ships with Jitsi

Jitsi comes needs an XMPP server as part of its infrastructure and uses Prosody, so if you're running a Jitsi, then you can easily add another virtual hosts configuration for a dedicated XMPP server as well using the same procedure shown above.

Troubleshooting

Familiarise yourself with the default configuration in /etc/prosody/prosody.cfg.lua so you know what settings and modules are available and what the defaults are. You can set the logging level to "debug", and check the output of prosodyctl about, prosodyctl status and prosodyctl check.

See also

• Prosody modules
• Official example configuration
• Debian's Prosody installation page
• Some good configuration examples
• Jitsi