1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
|
*******************
Modern XMPP Server
*******************
This is what I did to configure my XMPP server, using only `packages
supported in Debian <https://www.debian.org/security/>`_ and 100%
compliant with the `tests for XEP-0459: XMPP Compliance Suites 2022 on
conversations' website <https://compliance.conversations.im>`_.
This guide was originally written for prosody 0.9 under Debian jessie,
but is being kept up to date as I upgrade my server to new Debian
releases.
.. only:: html
.. contents::
How
===
I've decided to install prosody_, mostly because it was recommended by
the `RTC QuickStart Guide`_; I've heard that similar results can be
reached with ejabberd_ and other servers.
.. _prosody: https://prosody.im/
.. _`RTC QuickStart Guide`: http://rtcquickstart.org/
.. _ejabberd: https://www.ejabberd.im/
I'm also targetting Debian_ stable (+ backports_); currently that's
bookworm and prosody 0.12.
.. _Debian: https://www.debian.org
.. _backports: https://backports.debian.org/
Installation and prerequisites
------------------------------
You will need to install the packages ``prosody``, ``prosody-modules``,
and ``coturn``.
You also need to setup some TLS certificates (I used `Let's Encrypt`_);
and make them readable by the ``prosody`` user; you can see `Chapter 12
of the RTC QuickStart Guide
<http://rtcquickstart.org/guide/multi/xmpp-server-prosody.html>`_ for
more details.
.. _`Let's Encrypt`: https://letsencrypt.org/
Then see the `prosody documentation on certificates
<https://prosody.im/doc/certificates>`_ to see where to put certificates
so that prosody is able to autodetect them.
If the autodetection fails, you can use a configuration stanza such as
the following to explicitely set a certificate location::
https_ssl = {
certificate = "/etc/ssl/public/example.org.pem";
key = "/etc/ssl/private/example.org-key.pem";
}
legacy_ssl_ssl = {
certificate = "/etc/ssl/public/example.org.pem";
key = "/etc/ssl/private/example.org-key.pem";
}
On your firewall, you'll need to open the following TCP ports:
* 5222 (client2server)
* 5223 (client2server, https)
* 5269 (server2server)
* 5280 (default http port for prosody)
* 5281 (default https port for prosody)
* 3478 (coturn)
As well as the following port for UDP
* 3478 (coturn)
The http ports are needed to enable some services provided via http(s),
including rich media transfers.
With just a handful of users, I didn't bother to configure LDAP or
anything else, but just created users manually via::
prosodyctl adduser alice@example.org
prosody configuration
---------------------
You can then start configuring prosody by editing
``/etc/prosody/prosody.cfg.lua`` and changing a few values from the
distribution defaults.
First of all, enforce the use of certificate checking for server2server
communications with::
s2s_secure_auth = true
and then, if you need to, add to the whitelist any server that you want
to talk to and doesn't support secure s2s communication (but note that
gmail.com is no longer needed nor useful, as it doesn't support xmpp any
longer)::
s2s_insecure_domains = { "gmail.com" }
Also add at least an user (that you have already created with ``prosodyctl
adduser`` as described above) as an admin::
admins = { "alice@example.org" }
disabling in-band registration
-------------------------------
``mod_register`` is now enabled by default to provide password changing
services, but unless you have the resources to moderate new users you
probably want to disable registration to prevent the server from being
used to send spim_; to do so add the line::
allow_registration = false
.. _spim: https://en.wikipedia.org/wiki/Messaging_spam
TURN/STUN
---------
Support for video calls requires an external STUN / TURN server such as
coturn_, which can be installed on the same machine; its configuration
require setting a realm and a secret for auth in
``/etc/turnserver.conf``::
realm=turn.chat.example.org
use-auth-secret
static-auth-secret=<a long random string>
And then you will have to set the same values in
``/etc/prosody/prosody.cfg.lua``::
turncredentials_host = 'turn.chat.example.org'
turncredentials_secret = '<the same long string as above>'
.. _coturn: https://github.com/coturn/coturn/
virtualhosts
------------
For each virtualhost you want to configure, create a file
``/etc/prosody/conf.avail/chat.example.org.cfg.lua`` with contents like
the following::
VirtualHost "chat.example.org"
enabled = true
ssl = {
key = "/etc/ssl/private/example.org-key.pem";
certificate = "/etc/ssl/public/example.org.pem";
}
For the domains where you also want to enable MUCs, add the follwing
lines::
Component "conference.chat.example.org" "muc"
restrict_room_creation = "local"
modules_enabled = {
"mam_muc",
"vcard_muc",
}
the ``"local"`` configures prosody so that only local users are allowed
to create new rooms (but then everybody can join them, if the room
administrator allows it): this may help reduce unwanted usages of your
server by random people.
Enabling the ``mam_muc`` module (on prosody 0.10 only) allows people to
syncronize message history between multiple clients (XEP-0313)
You can also add the following line to enable rich media transfers via
http uploads (XEP-0363_)::
Component "upload.chat.example.org" "http_upload"
The defaults are pretty sane, but see
https://modules.prosody.im/mod_http_upload.html for details on what
knobs you can configure for this module; you may want e.g. to change the
maximum file size limit and setup an expiry date::
Component "upload.chat.example.org" "http_upload"
http_upload_file_size_limit = 1024 * 1024 * 2
http_upload_expire_after = 60 * 60 * 24 * 7
.. _XEP-0363: https://xmpp.org/extensions/xep-0363.html
Don't forget to enable the virtualhost by linking the file inside
``/etc/prosody/conf.d/``.
additional modules
------------------
Most of the other interesting XEPs are enabled by loading additional
modules inside ``/etc/prosody/prosody.cfg.lua`` (under
``modules_enabled``); to enable ``mod_something`` just add a line like::
"something";
Most of these come from the ``prosody-modules`` package (and thus from
https://modules.prosody.im/ ).
``mod_mam`` (XEP-0313)
Archive messages on the server for a limited period of time (default
1 week) and allow clients to retrieve them; this is required to
syncronize message history between multiple clients.
With prosody 0.9 only an in-memory storage backend is available,
which may make this module problematic on servers with many users.
prosody 0.10 will fix this by adding support for an SQL backed
storage with archiving capabilities.
``mod_throttle_presence`` + ``mod_filter_chatstates`` (XEP-0352)
Filter out presence updates and chat states when the client announces
(via Client State Indication) that the user isn't looking.
This is useful to reduce power and bandwidth usage for "useless"
traffic.
``cloud_notify`` (XEP-0357)
Allow clients to register an “app server” that is notified about new
messages
Proxied file transfers
----------------------
To enable proxied file transfers for clients behind NAT or firewalls,
you need to add ``"proxy65";`` to the list of additional modules, and
then enable it in at least one virtual host with the lines::
Component "proxy.chat.trueelena.org" "proxy65"
proxy65_address = "proxy.chat.trueelena.org"
See also
========
* `The State of Mobile XMPP in 2016 <https://gultsch.de/xmpp_2016.html>`_
(blog post by the maintainer of Conversations)
* `Prosody installation instructions in the FreedomBox wiki
<https://wiki.debian.org/FreedomBox/Configs/Prosody>`_
(for basic prosody configuration)
* `What Prosody modules do I need to support Conversations?
<https://serverfault.com/questions/835635/what-prosody-modules-do-i-need-to-support-conversations/835636>`_
(on Server Fault)
* `This HOWTO on my old website
<https://www.trueelena.org/computers/howto/modern_xmpp_server.html>`_
* `Enrico's post on how we configured the server before compliance.conversations.im was a thing <http://www.enricozini.org/blog/2017/debian/modern-and-secure-instant-messaging/>`_
* `Setting up XMPP (Prosody) on Debian Bookworm
<https://blog.hetherington.uk/2024/12/setting-up-xmpp-prosody-on-debian-bookworm/>`_ (another howto)
..
vim: set filetype=rst:
|
