From f5b1e6bc215bf82d4a294891e7c4a2b178122731 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A9lix=20Baylac-Jacqu=C3=A9?= Date: Fri, 1 May 2020 19:11:24 +0200 Subject: [PATCH] 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 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... --- nixos/modules/services/networking/prosody.nix | 2 +- nixos/modules/services/networking/prosody.xml | 88 +++++++++++++++++++ 2 files changed, 89 insertions(+), 1 deletion(-) create mode 100644 nixos/modules/services/networking/prosody.xml diff --git a/nixos/modules/services/networking/prosody.nix b/nixos/modules/services/networking/prosody.nix index 83e397e50fa..9825613d809 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 00000000000..7859cb1578b --- /dev/null +++ b/nixos/modules/services/networking/prosody.xml @@ -0,0 +1,88 @@ + + Prosody + + Prosody is an open-source, modern XMPP server. + +
+ Basic usage + + + 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! + + + + 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 + XEP-0423. + + + 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 + Multi User Chat (MUC) + and the HTTP File Upload ones. + You'll need to create a DNS subdomain for each of those. The current convention is to name your + MUC endpoint conference.example.org and your HTTP upload domain upload.example.org. + + + A good configuration to start with, including a + Multi User Chat (MUC) + endpoint as well as a HTTP File Upload + endpoint will look like this: + +services.prosody = { + enable = true; + admins = [ "root@example.org" ]; + ssl.cert = "/var/lib/acme/example.org/fullchain.pem"; + ssl.key = "/var/lib/acme/example.org/key.pem"; + virtualHosts."example.org" = { + enabled = true; + domain = "example.org"; + ssl.cert = "/var/lib/acme/example.org/fullchain.pem"; + ssl.key = "/var/lib/acme/example.org/key.pem"; + }; + muc = [ { + domain = "conference.example.org"; + } ]; + uploadHttp = { + domain = "upload.example.org"; + }; +}; + +
+
+ Let's Encrypt Configuration + + As you can see in the code snippet from the + previous section, + 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 + extraDomains module option. + + + Provided the setup detailed in the previous section, you'll need the following acme configuration to generate + a TLS certificate for the three endponits: + +security.acme = { + email = "root@example.org"; + acceptTerms = true; + certs = { + "example.org" = { + webroot = "/var/www/example.org"; + email = "root@example.org"; + extraDomains."conference.example.org" = null; + extraDomains."upload.example.org" = null; + }; + }; +}; + +
+