Messaging Services (GNU Guix Reference Manual)

10.9.13 Messaging Services

The (gnu services messaging) module provides Guix service definitions for messaging services. Currently it provides the following services:

Prosody Service

Scheme Variable: prosody-service-type

This is the type for the Prosody XMPP communication server. Its value must be a prosody-configuration record as in this example:

(service prosody-service-type
         (prosody-configuration
          (modules-enabled (cons* "groups" "mam" %default-modules-enabled))
          (int-components
           (list
            (int-component-configuration
             (hostname "conference.example.net")
             (plugin "muc")
             (mod-muc (mod-muc-configuration)))))
          (virtualhosts
           (list
            (virtualhost-configuration
             (domain "example.net"))))))

See below for details about prosody-configuration.

By default, Prosody does not need much configuration. Only one virtualhosts field is needed: it specifies the domain you wish Prosody to serve.

You can perform various sanity checks on the generated configuration with the prosodyctl check command.

Prosodyctl will also help you to import certificates from the letsencrypt directory so that the prosody user can access them. See https://prosody.im/doc/letsencrypt.

prosodyctl --root cert import /etc/letsencrypt/live

The available configuration parameters follow. Each parameter definition is preceded by its type; for example, ‘string-list foo’ indicates that the foo parameter should be specified as a list of strings. Types starting with maybe- denote parameters that won’t show up in prosody.cfg.lua when their value is 'disabled.

There is also a way to specify the configuration as a string, if you have an old prosody.cfg.lua file that you want to port over from some other system; see the end for more details.

The file-object type designates either a file-like object (see file-like objects) or a file name.

Available prosody-configuration fields are:

prosody-configuration parameter: package prosody: The Prosody package.

prosody-configuration parameter: file-name data-path: Location of the Prosody data storage directory. See https://prosody.im/doc/configure. Defaults to ‘"/var/lib/prosody"’.

prosody-configuration parameter: file-object-list plugin-paths: Additional plugin directories. They are searched in all the specified paths in order. See https://prosody.im/doc/plugins_directory. Defaults to ‘()’.

prosody-configuration parameter: file-name certificates: Every virtual host and component needs a certificate so that clients and servers can securely verify its identity. Prosody will automatically load certificates/keys from the directory specified here. Defaults to ‘"/etc/prosody/certs"’.

prosody-configuration parameter: string-list admins: This is a list of accounts that are admins for the server. Note that you must create the accounts separately. See https://prosody.im/doc/admins and https://prosody.im/doc/creating_accounts. Example: (admins '("user1@example.com" "user2@example.net")) Defaults to ‘()’.

prosody-configuration parameter: boolean use-libevent?: Enable use of libevent for better performance under high load. See https://prosody.im/doc/libevent. Defaults to ‘#f’.

prosody-configuration parameter: module-list modules-enabled: This is the list of modules Prosody will load on startup. It looks for mod_modulename.lua in the plugins folder, so make sure that exists too. Documentation on modules can be found at: https://prosody.im/doc/modules. Defaults to ‘("roster" "saslauth" "tls" "dialback" "disco" "carbons" "private" "blocklist" "vcard" "version" "uptime" "time" "ping" "pep" "register" "admin_adhoc")’.

prosody-configuration parameter: string-list modules-disabled: ‘"offline"’, ‘"c2s"’ and ‘"s2s"’ are auto-loaded, but should you want to disable them then add them to this list. Defaults to ‘()’.

prosody-configuration parameter: file-object groups-file: Path to a text file where the shared groups are defined. If this path is empty then ‘mod_groups’ does nothing. See https://prosody.im/doc/modules/mod_groups. Defaults to ‘"/var/lib/prosody/sharedgroups.txt"’.

prosody-configuration parameter: boolean allow-registration?: Disable account creation by default, for security. See https://prosody.im/doc/creating_accounts. Defaults to ‘#f’.

prosody-configuration parameter: maybe-ssl-configuration ssl

These are the SSL/TLS-related settings. Most of them are disabled so to use Prosody’s defaults. If you do not completely understand these options, do not add them to your config, it is easy to lower the security of your server using them. See https://prosody.im/doc/advanced_ssl_config.

Available ssl-configuration fields are:

ssl-configuration parameter: maybe-string protocol: This determines what handshake to use.

ssl-configuration parameter: maybe-file-name key: Path to your private key file.

ssl-configuration parameter: maybe-file-name certificate: Path to your certificate file.

ssl-configuration parameter: file-object capath: Path to directory containing root certificates that you wish Prosody to trust when verifying the certificates of remote servers. Defaults to ‘"/etc/ssl/certs"’.

ssl-configuration parameter: maybe-file-object cafile: Path to a file containing root certificates that you wish Prosody to trust. Similar to capath but with all certificates concatenated together.

ssl-configuration parameter: maybe-string-list verify: A list of verification options (these mostly map to OpenSSL’s set_verify() flags).

ssl-configuration parameter: maybe-string-list options: A list of general options relating to SSL/TLS. These map to OpenSSL’s set_options(). For a full list of options available in LuaSec, see the LuaSec source.

ssl-configuration parameter: maybe-non-negative-integer depth: How long a chain of certificate authorities to check when looking for a trusted root certificate.

ssl-configuration parameter: maybe-string ciphers: An OpenSSL cipher string. This selects what ciphers Prosody will offer to clients, and in what order.

ssl-configuration parameter: maybe-file-name dhparam: A path to a file containing parameters for Diffie-Hellman key exchange. You can create such a file with: openssl dhparam -out /etc/prosody/certs/dh-2048.pem 2048

ssl-configuration parameter: maybe-string curve: Curve for Elliptic curve Diffie-Hellman. Prosody’s default is ‘"secp384r1"’.

ssl-configuration parameter: maybe-string-list verifyext: A list of “extra” verification options.

ssl-configuration parameter: maybe-string password: Password for encrypted private keys.

prosody-configuration parameter: boolean c2s-require-encryption?: Whether to force all client-to-server connections to be encrypted or not. See https://prosody.im/doc/modules/mod_tls. Defaults to ‘#f’.

prosody-configuration parameter: string-list disable-sasl-mechanisms: Set of mechanisms that will never be offered. See https://prosody.im/doc/modules/mod_saslauth. Defaults to ‘("DIGEST-MD5")’.

prosody-configuration parameter: boolean s2s-require-encryption?: Whether to force all server-to-server connections to be encrypted or not. See https://prosody.im/doc/modules/mod_tls. Defaults to ‘#f’.

prosody-configuration parameter: boolean s2s-secure-auth?: Whether to require encryption and certificate authentication. This provides ideal security, but requires servers you communicate with to support encryption AND present valid, trusted certificates. See https://prosody.im/doc/s2s#security. Defaults to ‘#f’.

prosody-configuration parameter: string-list s2s-insecure-domains: Many servers don’t support encryption or have invalid or self-signed certificates. You can list domains here that will not be required to authenticate using certificates. They will be authenticated using DNS. See https://prosody.im/doc/s2s#security. Defaults to ‘()’.

prosody-configuration parameter: string-list s2s-secure-domains: Even if you leave s2s-secure-auth? disabled, you can still require valid certificates for some domains by specifying a list here. See https://prosody.im/doc/s2s#security. Defaults to ‘()’.

prosody-configuration parameter: string authentication: Select the authentication backend to use. The default provider stores passwords in plaintext and uses Prosody’s configured data storage to store the authentication data. If you do not trust your server please see https://prosody.im/doc/modules/mod_auth_internal_hashed for information about using the hashed backend. See also https://prosody.im/doc/authentication Defaults to ‘"internal_plain"’.

prosody-configuration parameter: maybe-string log: Set logging options. Advanced logging configuration is not yet supported by the Prosody service. See https://prosody.im/doc/logging. Defaults to ‘"*syslog"’.

prosody-configuration parameter: file-name pidfile: File to write pid in. See https://prosody.im/doc/modules/mod_posix. Defaults to ‘"/var/run/prosody/prosody.pid"’.

prosody-configuration parameter: maybe-non-negative-integer http-max-content-size: Maximum allowed size of the HTTP body (in bytes).

prosody-configuration parameter: maybe-string http-external-url: Some modules expose their own URL in various ways. This URL is built from the protocol, host and port used. If Prosody sits behind a proxy, the public URL will be http-external-url instead. See https://prosody.im/doc/http#external_url.

prosody-configuration parameter: virtualhost-configuration-list virtualhosts

A host in Prosody is a domain on which user accounts can be created. For example if you want your users to have addresses like ‘"john.smith@example.com"’ then you need to add a host ‘"example.com"’. All options in this list will apply only to this host.

Note: the name virtual host is used in configuration to avoid confusion with the actual physical host that Prosody is installed on. A single Prosody instance can serve many domains, each one defined as a VirtualHost entry in Prosody’s configuration. Conversely a server that hosts a single domain would have just one VirtualHost entry.

See https://prosody.im/doc/configure#virtual_host_settings.

Available virtualhost-configuration fields are:

all these prosody-configuration fields: admins, use-libevent?, modules-enabled, modules-disabled, groups-file, allow-registration?, ssl, c2s-require-encryption?, disable-sasl-mechanisms, s2s-require-encryption?, s2s-secure-auth?, s2s-insecure-domains, s2s-secure-domains, authentication, log, http-max-content-size, http-external-url, raw-content, plus:

virtualhost-configuration parameter: string domain: Domain you wish Prosody to serve.

prosody-configuration parameter: int-component-configuration-list int-components

Components are extra services on a server which are available to clients, usually on a subdomain of the main server (such as ‘"mycomponent.example.com"’). Example components might be chatroom servers, user directories, or gateways to other protocols.

Internal components are implemented with Prosody-specific plugins. To add an internal component, you simply fill the hostname field, and the plugin you wish to use for the component.

See https://prosody.im/doc/components. Defaults to ‘()’.

Available int-component-configuration fields are:

int-component-configuration parameter: string hostname: Hostname of the component.

int-component-configuration parameter: string plugin: Plugin you wish to use for the component.

int-component-configuration parameter: maybe-mod-muc-configuration mod-muc

Multi-user chat (MUC) is Prosody’s module for allowing you to create hosted chatrooms/conferences for XMPP users.

General information on setting up and using multi-user chatrooms can be found in the “Chatrooms” documentation (https://prosody.im/doc/chatrooms), which you should read if you are new to XMPP chatrooms.

Available mod-muc-configuration fields are:

mod-muc-configuration parameter: string name: The name to return in service discovery responses. Defaults to ‘"Prosody Chatrooms"’.

mod-muc-configuration parameter: string-or-boolean restrict-room-creation: If ‘#t’, this will only allow admins to create new chatrooms. Otherwise anyone can create a room. The value ‘"local"’ restricts room creation to users on the service’s parent domain. E.g. ‘user@example.com’ can create rooms on ‘rooms.example.com’. The value ‘"admin"’ restricts to service administrators only. Defaults to ‘#f’.

mod-muc-configuration parameter: non-negative-integer max-history-messages: Maximum number of history messages that will be sent to the member that has just joined the room. Defaults to ‘20’.

prosody-configuration parameter: ext-component-configuration-list ext-components

External components use XEP-0114, which most standalone components support. To add an external component, you simply fill the hostname field. See https://prosody.im/doc/components. Defaults to ‘()’.

Available ext-component-configuration fields are:

ext-component-configuration parameter: string component-secret: Password which the component will use to log in.

ext-component-configuration parameter: string hostname: Hostname of the component.

prosody-configuration parameter: non-negative-integer-list component-ports: Port(s) Prosody listens on for component connections. Defaults to ‘(5347)’.

prosody-configuration parameter: string component-interface: Interface Prosody listens on for component connections. Defaults to ‘"127.0.0.1"’.

prosody-configuration parameter: maybe-raw-content raw-content: Raw content that will be added to the configuration file.

It could be that you just want to get a prosody.cfg.lua up and running. In that case, you can pass an opaque-prosody-configuration record as the value of prosody-service-type. As its name indicates, an opaque configuration does not have easy reflective capabilities. Available opaque-prosody-configuration fields are:

opaque-prosody-configuration parameter: package prosody: The prosody package.

opaque-prosody-configuration parameter: string prosody.cfg.lua: The contents of the prosody.cfg.lua to use.

For example, if your prosody.cfg.lua is just the empty string, you could instantiate a prosody service like this:

(service prosody-service-type
         (opaque-prosody-configuration
          (prosody.cfg.lua "")))

BitlBee Service

BitlBee is a gateway that provides an IRC interface to a variety of messaging protocols such as XMPP.

Scheme Variable: bitlbee-service-type

This is the service type for the BitlBee IRC gateway daemon. Its value is a bitlbee-configuration (see below).

To have BitlBee listen on port 6667 on localhost, add this line to your services:

(service bitlbee-service-type)

Data Type: bitlbee-configuration

This is the configuration for BitlBee, with the following fields:

interface (default: "127.0.0.1")

port (default: 6667)

Listen on the network interface corresponding to the IP address specified in interface, on port.

When interface is 127.0.0.1, only local clients can connect; when it is 0.0.0.0, connections can come from any networking interface.

bitlbee (default: bitlbee)

The BitlBee package to use.

plugins (default: '())

List of plugin packages to use—e.g., bitlbee-discord.

extra-settings (default: "")

Configuration snippet added as-is to the BitlBee configuration file.

Quassel Service

Quassel is a distributed IRC client, meaning that one or more clients can attach to and detach from the central core.

Scheme Variable: quassel-service-type: This is the service type for the Quassel IRC backend daemon. Its value is a quassel-configuration (see below).

Data Type: quassel-configuration

This is the configuration for Quassel, with the following fields:

quassel (default: quassel): The Quassel package to use.
interface (default: "::,0.0.0.0")
port (default: 4242): Listen on the network interface(s) corresponding to the IPv4 or IPv6 interfaces specified in the comma delimited interface, on port.
loglevel (default: "Info"): The level of logging desired. Accepted values are Debug, Info, Warning and Error.