BoomMicrophone/nixpkgs-suyu
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

nixos/prosody: add NixOS manual entry

Browse source 
We add a Prosody entry to the NixOS manual showing how to setup a
basic XEP-0423 compliant Prosody service. This example also showcase
how to generate the associated ACME certificates.

Note: The <programlisting> body might look poorly indented, but trust
me, it's necessary. If we try to increase their indentation level, the
HTML output will end up containing a lot of unecesseray heading spaces
breaking the formatting...
This commit is contained in:
Félix Baylac-Jacqué 2020-05-01 19:11:24 +02:00
parent 353a8b58e6
commit f5b1e6bc21
No known key found for this signature in database
GPG key ID: EFD315F31848DBA4
2 changed files with 89 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
nixos/modules/services/networking/prosody.nix
View file

@ -873,5 +873,5 @@ in
};
};
meta.doc = ./prosody.xml;
}

88
nixos/modules/services/networking/prosody.xml Normal file
View file

@ -0,0 +1,88 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
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.
You'll 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:
<programlisting>
services.prosody = {
<link linkend="opt-services.prosody.enable">enable</link> = true;
<link linkend="opt-services.prosody.admins">admins</link> = [ "root@example.org" ];
<link linkend="opt-services.prosody.ssl.cert">ssl.cert</link> = "/var/lib/acme/example.org/fullchain.pem";
<link linkend="opt-services.prosody.ssl.key">ssl.key</link> = "/var/lib/acme/example.org/key.pem";
<link linkend="opt-services.prosody.virtualHosts">virtualHosts</link>."example.org" = {
<link linkend="opt-services.prosody.virtualHosts._name__.enabled">enabled</link> = true;
<link linkend="opt-services.prosody.virtualHosts._name__.domain">domain</link> = "example.org";
<link linkend="opt-services.prosody.virtualHosts._name__.ssl.cert">ssl.cert</link> = "/var/lib/acme/example.org/fullchain.pem";
<link linkend="opt-services.prosody.virtualHosts._name__.ssl.key">ssl.key</link> = "/var/lib/acme/example.org/key.pem";
};
<link linkend="opt-services.prosody.muc">muc</link> = [ {
<link linkend="opt-services.prosody.muc">domain</link> = "conference.example.org";
} ];
<link linkend="opt-services.prosody.uploadHttp">uploadHttp</link> = {
<link linkend="opt-services.prosody.uploadHttp.domain">domain</link> = "upload.example.org";
};
};</programlisting>
</para>
</section>
<section xml:id="module-services-prosody-letsencrypt">
<title>Let's Encrypt Configuration</title>
<para>
As you can see in the code snippet from the
<link linkend="module-services-prosody-basic-usage">previous section</link>,
you'll 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_.extraDomains">extraDomains</link> module option.
</para>
<para>
Provided the setup detailed in the previous section, you'll need the following acme configuration to generate
a TLS certificate for the three endponits:
<programlisting>
security.acme = {
<link linkend="opt-security.acme.email">email</link> = "root@example.org";
<link linkend="opt-security.acme.acceptTerms">acceptTerms</link> = true;
<link linkend="opt-security.acme.certs">certs</link> = {
"example.org" = {
<link linkend="opt-security.acme.certs._name_.webroot">webroot</link> = "/var/www/example.org";
<link linkend="opt-security.acme.certs._name_.email">email</link> = "root@example.org";
<link linkend="opt-security.acme.certs._name_.extraDomains">extraDomains."conference.example.org"</link> = null;
<link linkend="opt-security.acme.certs._name_.extraDomains">extraDomains."upload.example.org"</link> = null;
};
};
};</programlisting>
</para>
</section>
</chapter>