nixos/modules/services/networking/prosody.xml

   1 <chapter xmlns="http://docbook.org/ns/docbook"
   2          xmlns:xlink="http://www.w3.org/1999/xlink"
   3          xmlns:xi="http://www.w3.org/2001/XInclude"
   4          version="5.0"
   5          xml:id="module-services-prosody">
   6  <title>Prosody</title>
   7  <para>
   8   <link xlink:href="https://prosody.im/">Prosody</link> is an open-source, modern XMPP server.
   9  </para>
  10  <section xml:id="module-services-prosody-basic-usage">
  11   <title>Basic usage</title>
  12
  13   <para>
  14     A common struggle for most XMPP newcomers is to find the right set
  15     of XMPP Extensions (XEPs) to setup. Forget to activate a few of
  16     those and your XMPP experience might turn into a nightmare!
  17   </para>
  18
  19   <para>
  20     The XMPP community tackles this problem by creating a meta-XEP
  21     listing a decent set of XEPs you should implement. This meta-XEP
  22     is issued every year, the 2020 edition being
  23     <link xlink:href="https://xmpp.org/extensions/xep-0423.html">XEP-0423</link>.
  24   </para>
  25   <para>
  26     The NixOS Prosody module will implement most of these recommendend XEPs out of
  27     the box. That being said, two components still require some
  28     manual configuration: the
  29     <link xlink:href="https://xmpp.org/extensions/xep-0045.html">Multi User Chat (MUC)</link>
  30     and the <link xlink:href="https://xmpp.org/extensions/xep-0363.html">HTTP File Upload</link> ones.
  31     You'll need to create a DNS subdomain for each of those. The current convention is to name your
  32     MUC endpoint <literal>conference.example.org</literal> and your HTTP upload domain <literal>upload.example.org</literal>.
  33   </para>
  34   <para>
  35     A good configuration to start with, including a
  36     <link xlink:href="https://xmpp.org/extensions/xep-0045.html">Multi User Chat (MUC)</link>
  37     endpoint as well as a <link xlink:href="https://xmpp.org/extensions/xep-0363.html">HTTP File Upload</link>
  38     endpoint will look like this:
  39     <programlisting>
  40 services.prosody = {
  41   <link linkend="opt-services.prosody.enable">enable</link> = true;
  42   <link linkend="opt-services.prosody.admins">admins</link> = [ "root@example.org" ];
  43   <link linkend="opt-services.prosody.ssl.cert">ssl.cert</link> = "/var/lib/acme/example.org/fullchain.pem";
  44   <link linkend="opt-services.prosody.ssl.key">ssl.key</link> = "/var/lib/acme/example.org/key.pem";
  45   <link linkend="opt-services.prosody.virtualHosts">virtualHosts</link>."example.org" = {
  46       <link linkend="opt-services.prosody.virtualHosts._name_.enabled">enabled</link> = true;
  47       <link linkend="opt-services.prosody.virtualHosts._name_.domain">domain</link> = "example.org";
  48       <link linkend="opt-services.prosody.virtualHosts._name_.ssl.cert">ssl.cert</link> = "/var/lib/acme/example.org/fullchain.pem";
  49       <link linkend="opt-services.prosody.virtualHosts._name_.ssl.key">ssl.key</link> = "/var/lib/acme/example.org/key.pem";
  50   };
  51   <link linkend="opt-services.prosody.muc">muc</link> = [ {
  52       <link linkend="opt-services.prosody.muc">domain</link> = "conference.example.org";
  53   } ];
  54   <link linkend="opt-services.prosody.uploadHttp">uploadHttp</link> = {
  55       <link linkend="opt-services.prosody.uploadHttp.domain">domain</link> = "upload.example.org";
  56   };
  57 };</programlisting>
  58   </para>
  59  </section>
  60  <section xml:id="module-services-prosody-letsencrypt">
  61   <title>Let's Encrypt Configuration</title>
  62  <para>
  63    As you can see in the code snippet from the
  64    <link linkend="module-services-prosody-basic-usage">previous section</link>,
  65    you'll need a single TLS certificate covering your main endpoint,
  66    the MUC one as well as the HTTP Upload one. We can generate such a
  67    certificate by leveraging the ACME
  68    <link linkend="opt-security.acme.certs._name_.extraDomainNames">extraDomainNames</link> module option.
  69  </para>
  70  <para>
  71    Provided the setup detailed in the previous section, you'll need the following acme configuration to generate
  72    a TLS certificate for the three endponits:
  73     <programlisting>
  74 security.acme = {
  75   <link linkend="opt-security.acme.defaults.email">email</link> = "root@example.org";
  76   <link linkend="opt-security.acme.acceptTerms">acceptTerms</link> = true;
  77   <link linkend="opt-security.acme.certs">certs</link> = {
  78     "example.org" = {
  79       <link linkend="opt-security.acme.certs._name_.webroot">webroot</link> = "/var/www/example.org";
  80       <link linkend="opt-security.acme.certs._name_.email">email</link> = "root@example.org";
  81       <link linkend="opt-security.acme.certs._name_.extraDomainNames">extraDomainNames</link> = [ "conference.example.org" "upload.example.org" ];
  82     };
  83   };
  84 };</programlisting>
  85  </para>
  86 </section>
  87 </chapter>