diff options
author | Félix Baylac-Jacqué <felix@alternativebit.fr> | 2020-05-01 19:11:24 +0200 |
---|---|---|
committer | Félix Baylac-Jacqué <felix@alternativebit.fr> | 2020-05-01 19:57:33 +0200 |
commit | f5b1e6bc215bf82d4a294891e7c4a2b178122731 (patch) | |
tree | 7a7ffee6555f8e7b35653c404c48ba85a5c78c7e /nixos/modules | |
parent | 353a8b58e6b12daf2977870743a6dd85ee080448 (diff) |
nixos/prosody: add NixOS manual entry
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...
Diffstat (limited to 'nixos/modules')
-rw-r--r-- | nixos/modules/services/networking/prosody.nix | 2 | ||||
-rw-r--r-- | nixos/modules/services/networking/prosody.xml | 88 |
2 files changed, 89 insertions, 1 deletions
diff --git a/nixos/modules/services/networking/prosody.nix b/nixos/modules/services/networking/prosody.nix index 83e397e50fa0..9825613d809f 100644 --- a/nixos/modules/services/networking/prosody.nix +++ b/nixos/modules/services/networking/prosody.nix @@ -873,5 +873,5 @@ in }; }; - + meta.doc = ./prosody.xml; } diff --git a/nixos/modules/services/networking/prosody.xml b/nixos/modules/services/networking/prosody.xml new file mode 100644 index 000000000000..7859cb1578b7 --- /dev/null +++ b/nixos/modules/services/networking/prosody.xml @@ -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> |