Complete XMPP server with updated support for modern XEPs — ideal for Conversations
This Ansible role deploys a full Prosody XMPP server on your Fedora 25 (or higher) server. It also deploys a number of modules to make the operation of the server most battery-optimized and compatible with excellent features of modern chat clients such as Conversations, including:
- push support to greatly minimize idle battery use (via module
- stream management to improve operation in flaky connectivity (via module
- message archive management to receive queued messages after network changes (via module
- HTTP file upload to support (end-to-end encrypted) file transfer to (even offline) users (via module
- message carbons to get messages across all your devices (via module
- client state indication for superior battery life (via module
- simple blocking to make it easy to block annoying people (via module
- and more!
This is the compliance tester result for a server configured with the defaults this role ships with, and whose DNS server is configured according to the recommendations in this guide:
Use compliance suite 'Conversations Compliance Suite' to test example.com Server is Prosody 0.10.0 running XEP-0115: Entity Capabilities… PASSED running XEP-0163: Personal Eventing Protocol… PASSED running Roster Versioning… PASSED running XEP-0280: Message Carbons… PASSED running XEP-0191: Blocking Command… PASSED running XEP-0045: Multi-User Chat… PASSED running XEP-0198: Stream Management… PASSED running XEP-0313: Message Archive Management… PASSED running XEP-0352: Client State Indication… PASSED running XEP-0363: HTTP File Upload… PASSED running XEP-0065: SOCKS5 Bytestreams (Proxy)… PASSED running XEP-0357: Push Notifications… PASSED running XEP-0368: SRV records for XMPP over TLS… PASSED running XEP-0384: OMEMO Encryption… PASSED running XEP-0313: Message Archive Management (MUC)… FAILED passed 14/15
See the file
defaults/main.yml for more information on how to configure the
role from your playbook. Note that you may have to configure your Ansible's
At the very minimum, you will have to:
- define the
ssltree of settings for the domain you will run — the keys of the
ssltree define the domain name of your server;
- add a few JIDs with their initial passwords under
Removing accounts: defining a JID's password to be
None or empty string causes
the account to be deleted when the role is run.
Setting the variable
xmpp.conference.enabled to True enables the MUC
(multi-user-conference) feature. The variable
controls the subdomain used to name the MUC endpoint (it defaults to
Each one of your virtual hosts (derived from the
ssl variable) will gain
a conference endpoint named after the subdomain.
You need a DNS entry for the subdomain (
conference.example.com) if you
want people from other XMPP servers to join your conferences. It should probably
CNAME DNS entry pointing to your XMPP server's
A record. See below
in the DNS notes section.
xmpp.conference.creators can be set to "everyone" if you would
like anyone to create conference rooms, "admins" if you would like only the
server administrators to create conference rooms, and "local" if you'd like only
people with JIDs on your server to create conference rooms.
You can list external components (gateways) and their credentials under the
xmpp.components variable (see
defaults/main.yml for a sample.
A component will be added for each virtual host of your XMPP server.
The JID of the component will be the concatenation of the key and the domain
of the virtual host. The password of the component will be the value of
the component you listed.
Here is a sample:
ssl: ... example.com: ... xmpp: ... components: fbgateway: ARSNE2ki24n908rARTN2e34ni23 # This would declare a component JID "fbgateway.example.com" # in the Prosody configuration. ...
Do not forget that you need a DNS entry for the component as well. This entry should probably be created similarly to the DNS entry for the conference service.
Once you have listed your components and applied the configuration, you can set up the external components such as http://spectrum.im. This repository has a role which will set up Spectrum for you as an external component on the same server as your Prosody XMPP server.
You will need to open TCP ports on the machine that will act as XMPP server:
This role works out of the box with SELinux policy as it ships in Fedora.
Changes to any of the three default ports in variables
likely cause Prosody to fail to listen to said ports. You will have to add a
type enforcement exception for your desired port.
selinux-module in this repo for more information on how to
add exceptions for services.
See the instructions for the
mailserver role in this repo to understand how
to configure the SSL certificates for your XMPP server.
The SSL certificate must be for the "virtual domain" of your server, not for the hostname or IP of the actual machine that will run the XMPP service. See https://prosody.im/doc/certificates for more information on that.
You will need to add DNS records for your client to find the server.
Assuming your server (and the SSL certificate) are
example.com, here is a
good example of how the DNS records in the
example.com zone file would look like:
$ttl 38400 @ IN SOA ns1.example.com. example.example.com. ( 2017020603 1800 1800 604800 1800 ) IN NS ns1.example.com. IN NS ns1.backupdns.com. IN A 220.127.116.11 . . . xmpp IN A 18.104.22.168 _xmpp-client._tcp IN SRV 5 5 5222 xmpp.example.com. _xmpp-server._tcp IN SRV 5 5 5269 xmpp.example.com. _xmpps-client._tcp IN SRV 0 5 5223 xmpp.example.com. conference IN CNAME xmpp . . .
As you can see, you have an
A record for your XMPP server, followed
by a number of
SRV records pointing to your
A record, then
CNAME record for the conference server. These records prioritize
client connections over SSL rather than STARTTLS, for added privacy.
For the purposes of SSL validation, clients will not treat your
server as if its domain was the full
— they will instead treat your server's domain as as
Of course, if you set any of the
xmpp.ports.* variables to
(which disables the use of the port set to
False), then remove
the corresponding DNS record for that port. Correspondingly, if you change
any of these ports, you should adjust your DNS configuration to match.
Naturally, if you disable conference support, or change the subdomain used for the conference server, you must either remove the DNS entry for it, or alter it to matche the subdomain.
See https://prosody.im/doc/dns for more information on the matter.
Check you have met the prerequisites.
Create a playbook that includes this role.
In that playbook, override the default variables available in
defaults/main.yml with variables of your own that make sense for
your use case.
Then simply run your new playbook against your intended Fedora server.