diff options
Diffstat (limited to 'nixos/modules/services/networking/prosody.xml')
-rw-r--r-- | nixos/modules/services/networking/prosody.xml | 87 |
1 files changed, 87 insertions, 0 deletions
diff --git a/nixos/modules/services/networking/prosody.xml b/nixos/modules/services/networking/prosody.xml new file mode 100644 index 00000000000..6358d744ff7 --- /dev/null +++ b/nixos/modules/services/networking/prosody.xml @@ -0,0 +1,87 @@ +<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_.extraDomainNames">extraDomainNames</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.defaults.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_.extraDomainNames">extraDomainNames</link> = [ "conference.example.org" "upload.example.org" ]; + }; + }; +};</programlisting> + </para> +</section> +</chapter> |