depot/third_party/nixpkgs/nixos/modules/services/networking/prosody.xml
Default email 0d9fc34957 Project import generated by Copybara.
GitOrigin-RevId: 5ed481943351e9fd354aeb557679624224de38d5
2023-01-20 11:41:00 +01:00

92 lines
3.7 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!-- Do not edit this file directly, edit its companion .md instead
and regenerate this file using nixos/doc/manual/md-to-db.sh -->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-prosody">
<title>Prosody</title>
<para>
<link xlink:href="https://prosody.im/">Prosody</link> is an
open-source, modern XMPP server.
</para>
<section xml:id="module-services-prosody-basic-usage">
<title>Basic usage</title>
<para>
A common struggle for most XMPP newcomers is to find the right set
of XMPP Extensions (XEPs) to setup. Forget to activate a few of
those and your XMPP experience might turn into a nightmare!
</para>
<para>
The XMPP community tackles this problem by creating a meta-XEP
listing a decent set of XEPs you should implement. This meta-XEP
is issued every year, the 2020 edition being
<link xlink:href="https://xmpp.org/extensions/xep-0423.html">XEP-0423</link>.
</para>
<para>
The NixOS Prosody module will implement most of these recommendend
XEPs out of the box. That being said, two components still require
some manual configuration: the
<link xlink:href="https://xmpp.org/extensions/xep-0045.html">Multi
User Chat (MUC)</link> and the
<link xlink:href="https://xmpp.org/extensions/xep-0363.html">HTTP
File Upload</link> ones. Youll need to create a DNS subdomain for
each of those. The current convention is to name your MUC endpoint
<literal>conference.example.org</literal> and your HTTP upload
domain <literal>upload.example.org</literal>.
</para>
<para>
A good configuration to start with, including a
<link xlink:href="https://xmpp.org/extensions/xep-0045.html">Multi
User Chat (MUC)</link> endpoint as well as a
<link xlink:href="https://xmpp.org/extensions/xep-0363.html">HTTP
File Upload</link> endpoint will look like this:
</para>
<programlisting>
services.prosody = {
enable = true;
admins = [ &quot;root@example.org&quot; ];
ssl.cert = &quot;/var/lib/acme/example.org/fullchain.pem&quot;;
ssl.key = &quot;/var/lib/acme/example.org/key.pem&quot;;
virtualHosts.&quot;example.org&quot; = {
enabled = true;
domain = &quot;example.org&quot;;
ssl.cert = &quot;/var/lib/acme/example.org/fullchain.pem&quot;;
ssl.key = &quot;/var/lib/acme/example.org/key.pem&quot;;
};
muc = [ {
domain = &quot;conference.example.org&quot;;
} ];
uploadHttp = {
domain = &quot;upload.example.org&quot;;
};
};
</programlisting>
</section>
<section xml:id="module-services-prosody-letsencrypt">
<title>Lets Encrypt Configuration</title>
<para>
As you can see in the code snippet from the
<link linkend="module-services-prosody-basic-usage">previous
section</link>, youll need a single TLS certificate covering your
main endpoint, the MUC one as well as the HTTP Upload one. We can
generate such a certificate by leveraging the ACME
<link linkend="opt-security.acme.certs._name_.extraDomainNames">extraDomainNames</link>
module option.
</para>
<para>
Provided the setup detailed in the previous section, youll need
the following acme configuration to generate a TLS certificate for
the three endponits:
</para>
<programlisting>
security.acme = {
email = &quot;root@example.org&quot;;
acceptTerms = true;
certs = {
&quot;example.org&quot; = {
webroot = &quot;/var/www/example.org&quot;;
email = &quot;root@example.org&quot;;
extraDomainNames = [ &quot;conference.example.org&quot; &quot;upload.example.org&quot; ];
};
};
};
</programlisting>
</section>
</chapter>