From 612781e8169bf13fde26091f2d6c55ebed6ccb6f Mon Sep 17 00:00:00 2001
From: Franz Pletz <fpletz@fnordicwalking.de>
Date: Sun, 6 Dec 2015 16:55:09 +0100
Subject: [PATCH 1/9] simp_le service: letsencrypt cert auto-renewal

This new service invokes `simp_le` for a defined set of certs on a regular
basis with a systemd timer. `simp_le` is smart enough to handle account
registration, domain validation and renewal on its own. The only thing
required is an existing HTTP server that serves the path
`/.well-known/acme-challenge` from the webroot cert parameter.

Example:

  services.simp_le.certs."foo.example.com" = {
    webroot = "/var/www/challenges";
    extraDomains = [ "www.example.com" ];
    email = "foo@example.com";
    validMin = 2592000;
    renewInterval = "weekly";
  };

Example Nginx vhost:

  services.nginx.appendConfig = ''
    http {
      server {
        server_name _;
        listen 80;
        listen [::]:80;

        location /.well-known/acme-challenge {
          root /var/www/challenges;
        }

        location / {
          return 301 https://$host$request_uri;
        }
      }
    }
  '';
---
 nixos/modules/module-list.nix               |   1 +
 nixos/modules/services/security/simp_le.nix | 133 ++++++++++++++++++++
 2 files changed, 134 insertions(+)
 create mode 100644 nixos/modules/services/security/simp_le.nix

diff --git a/nixos/modules/module-list.nix b/nixos/modules/module-list.nix
index 963daf721ad..c708f095f40 100644
--- a/nixos/modules/module-list.nix
+++ b/nixos/modules/module-list.nix
@@ -388,6 +388,7 @@
   ./services/security/hologram.nix
   ./services/security/munge.nix
   ./services/security/physlock.nix
+  ./services/security/simp_le.nix
   ./services/security/torify.nix
   ./services/security/tor.nix
   ./services/security/torsocks.nix
diff --git a/nixos/modules/services/security/simp_le.nix b/nixos/modules/services/security/simp_le.nix
new file mode 100644
index 00000000000..d578d5bb679
--- /dev/null
+++ b/nixos/modules/services/security/simp_le.nix
@@ -0,0 +1,133 @@
+{ config, lib, pkgs, ... }:
+
+with lib;
+
+let
+
+  cfg = config.services.simp_le;
+
+  certOpts = { ... }: {
+    options = {
+      webroot = mkOption {
+        type = types.nullOr types.str;
+        default = null;
+        description = "Where the webroot of the HTTP vhost is located.";
+      };
+
+      validMin = mkOption {
+        type = types.int;
+        default = 2592000;
+        description = "Minimum remaining validity before renewal in seconds.";
+      };
+
+      renewInterval = mkOption {
+        type = types.str;
+        default = "weekly";
+        description = "Systemd calendar expression when to check for renewal. See systemd.time(7).";
+      };
+
+      email = mkOption {
+        type = types.nullOr types.str;
+        default = null;
+        description = "Contact email address for the CA to be able to reach you.";
+      };
+
+      plugins = mkOption {
+        type = types.listOf (types.enum [
+          "cert.der" "cert.pem" "chain.der" "chain.pem" "external_pem.sh"
+          "fullchain.der" "fullchain.pem" "key.der" "key.pem"
+        ]);
+        default = [ "fullchain.pem" "key.pem" ];
+        description = "Plugins to enable.";
+      };
+
+      extraDomains = mkOption {
+        default = [ ];
+        type = types.listOf types.str;
+        description = "More domains to include in the certificate.";
+        example = [ "example.com" "foo.example.com:/var/www/foo" ];
+      };
+    };
+  };
+
+in
+
+{
+
+  ###### interface
+
+  options = {
+    services.simp_le = {
+      directory = mkOption {
+        default = "/etc/ssl";
+        type = types.str;
+        description = ''
+          Directory where certs will be stored by default.
+        '';
+      };
+
+      certs = mkOption {
+        default = { };
+        type = types.loaOf types.optionSet;
+        description = ''
+          Attribute set of certificates to get signed and renewed.
+        '';
+        options = [ certOpts ];
+        example = {
+          "foo.example.com" = {
+            webroot = "/var/www/challenges/";
+            email = "foo@example.com";
+            extraDomains = [ "www.example.com" "example.com" ];
+          };
+          "bar.example.com" = {
+            webroot = "/var/www/challenges/";
+            email = "bar@example.com";
+          };
+        };
+      };
+    };
+  };
+
+  ###### implementation
+  config = mkIf (cfg.certs != { }) {
+
+    systemd.services = flip mapAttrs' cfg.certs (cert: data: nameValuePair
+      ("simp_le-${cert}")
+      ({
+        description = "simp_le cert renewal for ${cert}";
+        after = [ "network.target" ];
+        serviceConfig = {
+          Type = "oneshot";
+          SuccessExitStatus = "0 1";
+        };
+        preStart = ''
+          mkdir -p "${cfg.directory}/${cert}"
+        '';
+        script = ''
+          WEBROOT="${optionalString (data.webroot == null) data.webroot}"
+          cd "${cfg.directory}/${cert}"
+          ${pkgs.simp_le}/bin/simp_le -v \
+            ${concatMapStringsSep " " (p: "-f ${p}") data.plugins} \
+            -d ${cert} --default_root "$WEBROOT" \
+            ${concatMapStringsSep " " (p: "-d ${p}") data.extraDomains} \
+            ${optionalString (data.email != null) "--email ${data.email}"} \
+            --valid_min ${toString data.validMin}
+        '';
+      })
+    );
+
+    systemd.timers = flip mapAttrs' cfg.certs (cert: data: nameValuePair
+      ("simp_le-${cert}")
+      ({
+        description = "timer for simp_le cert renewal of ${cert}";
+        wantedBy = [ "timers.target" ];
+        timerConfig = {
+          OnCalendar = data.renewInterval;
+          Unit = "simp_le-${cert}.service";
+        };
+      })
+    );
+
+  };
+
+}

From adc693f982d73af6611856579234f56e383245ad Mon Sep 17 00:00:00 2001
From: Nikolay Amiantov <ab@fmap.me>
Date: Tue, 8 Dec 2015 21:07:26 +0300
Subject: [PATCH 2/9] simp_le: 20151205 -> 20151207

---
 pkgs/tools/admin/simp_le/default.nix | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/pkgs/tools/admin/simp_le/default.nix b/pkgs/tools/admin/simp_le/default.nix
index 5f945309aac..43e361ba647 100644
--- a/pkgs/tools/admin/simp_le/default.nix
+++ b/pkgs/tools/admin/simp_le/default.nix
@@ -1,16 +1,16 @@
 { stdenv, fetchFromGitHub, pythonPackages }:
 
 pythonPackages.buildPythonPackage rec {
-  name = "simp_le-20151205";
+  name = "simp_le-20151207";
 
   src = fetchFromGitHub {
     owner = "kuba";
     repo = "simp_le";
-    rev = "976a33830759e66610970f92f6ec1a656a2c8335";
-    sha256 = "0bfa5081rmjjg9sii6pn2dskd1wh0dgrf9ic9hpisawrk0y0739i";
+    rev = "ac836bc0af988cb14dc0a83dc2039e7fa541b677";
+    sha256 = "0r07mlis81n0pmj74wjcvjpi6i3lkzs6hz8iighhk8yymn1a8rbn";
   };
 
-  propagatedBuildInputs = with pythonPackages; [ acme cryptography pytz requests2 ];
+  propagatedBuildInputs = with pythonPackages; [ acme ];
 
   meta = with stdenv.lib; {
     homepage = https://github.com/kuba/simp_le;

From 6906baae5c8686ac8d859b3af6083d8210c57d80 Mon Sep 17 00:00:00 2001
From: Nikolay Amiantov <ab@fmap.me>
Date: Tue, 8 Dec 2015 21:09:19 +0300
Subject: [PATCH 3/9] nixos/simp_le: improve configuration options

---
 nixos/modules/services/security/simp_le.nix | 101 +++++++++++++++-----
 1 file changed, 77 insertions(+), 24 deletions(-)

diff --git a/nixos/modules/services/security/simp_le.nix b/nixos/modules/services/security/simp_le.nix
index d578d5bb679..927359da0d3 100644
--- a/nixos/modules/services/security/simp_le.nix
+++ b/nixos/modules/services/security/simp_le.nix
@@ -9,9 +9,14 @@ let
   certOpts = { ... }: {
     options = {
       webroot = mkOption {
-        type = types.nullOr types.str;
-        default = null;
-        description = "Where the webroot of the HTTP vhost is located.";
+        type = types.str;
+        description = ''
+          Where the webroot of the HTTP vhost is located.
+          <filename>.well-known/acme-challenge/</filename> directory
+          will be created automatically if it doesn't exist.
+          <literal>http://example.org/.well-known/acme-challenge/</literal> must also
+          be available (notice unencrypted HTTP).
+        '';
       };
 
       validMin = mkOption {
@@ -32,20 +37,53 @@ let
         description = "Contact email address for the CA to be able to reach you.";
       };
 
+      user = mkOption {
+        type = types.str;
+        default = "root";
+        description = "User under which simp_le would run.";
+      };
+
+      group = mkOption {
+        type = types.str;
+        default = "root";
+        description = "Group under which simp_le would run.";
+      };
+
+      postRun = mkOption {
+        type = types.lines;
+        default = "";
+        example = "systemctl reload nginx.service";
+        description = ''
+          Commands to run after certificates are re-issued. Typically
+          the web server and other servers using certificates need to
+          be reloaded.
+        '';
+      };
+
       plugins = mkOption {
         type = types.listOf (types.enum [
           "cert.der" "cert.pem" "chain.der" "chain.pem" "external_pem.sh"
-          "fullchain.der" "fullchain.pem" "key.der" "key.pem"
+          "fullchain.der" "fullchain.pem" "key.der" "key.pem" "account_key.json"
         ]);
-        default = [ "fullchain.pem" "key.pem" ];
-        description = "Plugins to enable.";
+        default = [ "fullchain.pem" "key.pem" "account_key.json" ];
+        description = ''
+          Plugins to enable. With default settings simp_le will
+          store public certificate bundle in <filename>fullchain.pem</filename>
+          and private key in <filename>key.pem</filename> in its state directory.
+        '';
       };
 
       extraDomains = mkOption {
-        default = [ ];
-        type = types.listOf types.str;
-        description = "More domains to include in the certificate.";
-        example = [ "example.com" "foo.example.com:/var/www/foo" ];
+        type = types.attrsOf (types.nullOr types.str);
+        default = {};
+        example = {
+          "example.org" = "/srv/http/nginx";
+          "mydomain.org" = null;
+        };
+        description = ''
+          Extra domain names for which certificates are to be issued, with their
+          own server roots if needed.
+        '';
       };
     };
   };
@@ -62,7 +100,7 @@ in
         default = "/etc/ssl";
         type = types.str;
         description = ''
-          Directory where certs will be stored by default.
+          Directory where certs and other state will be stored by default.
         '';
       };
 
@@ -74,10 +112,10 @@ in
         '';
         options = [ certOpts ];
         example = {
-          "foo.example.com" = {
+          "example.com" = {
             webroot = "/var/www/challenges/";
             email = "foo@example.com";
-            extraDomains = [ "www.example.com" "example.com" ];
+            extraDomains = { "www.example.com" = null; "foo.example.com" = "/var/www/foo/"; };
           };
           "bar.example.com" = {
             webroot = "/var/www/challenges/";
@@ -91,27 +129,42 @@ in
   ###### implementation
   config = mkIf (cfg.certs != { }) {
 
-    systemd.services = flip mapAttrs' cfg.certs (cert: data: nameValuePair
+    systemd.services = flip mapAttrs' cfg.certs (cert: data:
+      let
+        cpath = "${cfg.directory}/${cert}";
+        cmdline = [ "-v" "-d" cert "--default_root" data.webroot "--valid_min" data.validMin ]
+                  ++ optionals (data.email != null) [ "--email" data.email ]
+                  ++ concatMap (p: [ "-f" p ]) data.plugins
+                  ++ concatLists (mapAttrsToList (name: root: [ "-d" (if root == null then name else "${name}:${root}")]) data.extraDomains);
+
+      in nameValuePair
       ("simp_le-${cert}")
       ({
         description = "simp_le cert renewal for ${cert}";
         after = [ "network.target" ];
         serviceConfig = {
           Type = "oneshot";
-          SuccessExitStatus = "0 1";
+          SuccessExitStatus = [ "0" "1" ];
         };
+        path = [ pkgs.simp_le pkgs.sudo ];
         preStart = ''
-          mkdir -p "${cfg.directory}/${cert}"
+          mkdir -p '${cfg.directory}'
+          if [ ! -d '${cpath}' ]; then
+            mkdir -m 700 '${cpath}'
+            chown '${data.user}:${data.group}' '${cpath}'
+          fi
         '';
         script = ''
-          WEBROOT="${optionalString (data.webroot == null) data.webroot}"
-          cd "${cfg.directory}/${cert}"
-          ${pkgs.simp_le}/bin/simp_le -v \
-            ${concatMapStringsSep " " (p: "-f ${p}") data.plugins} \
-            -d ${cert} --default_root "$WEBROOT" \
-            ${concatMapStringsSep " " (p: "-d ${p}") data.extraDomains} \
-            ${optionalString (data.email != null) "--email ${data.email}"} \
-            --valid_min ${toString data.validMin}
+          cd '${cpath}'
+          set +e
+          sudo -u '${data.user}' -- simp_le ${concatMapStringsSep " " (arg: escapeShellArg (toString arg)) cmdline}
+          EXITCODE=$?
+          set -e
+          if [ "$EXITCODE" = "0" ]; then
+            ${data.postRun}
+          else
+            exit "$EXITCODE"
+          fi
         '';
       })
     );

From 1641c19d0b367ebe9eca15f269c9f8dbf020c113 Mon Sep 17 00:00:00 2001
From: Nikolay Amiantov <ab@fmap.me>
Date: Tue, 8 Dec 2015 21:23:09 +0300
Subject: [PATCH 4/9] nixos/simp_le: use /var/lib/simp_le as root dir by
 default

/etc on NixOS is regenerated on boot and there was movement
towards making it read-only -- so let's keep dynamic state elsewhere.
---
 nixos/modules/services/security/simp_le.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/nixos/modules/services/security/simp_le.nix b/nixos/modules/services/security/simp_le.nix
index 927359da0d3..31eb89da55c 100644
--- a/nixos/modules/services/security/simp_le.nix
+++ b/nixos/modules/services/security/simp_le.nix
@@ -97,7 +97,7 @@ in
   options = {
     services.simp_le = {
       directory = mkOption {
-        default = "/etc/ssl";
+        default = "/var/lib/simp_le";
         type = types.str;
         description = ''
           Directory where certs and other state will be stored by default.

From e7362a877dd11493d23dcbbee390343b64c0a491 Mon Sep 17 00:00:00 2001
From: Franz Pletz <fpletz@fnordicwalking.de>
Date: Fri, 11 Dec 2015 17:30:45 +0100
Subject: [PATCH 5/9] nixos/simp_le: Use systemd for setting user and group

This is much cleaner and we don't depend on sudo.
---
 nixos/modules/services/security/simp_le.nix | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/nixos/modules/services/security/simp_le.nix b/nixos/modules/services/security/simp_le.nix
index 31eb89da55c..12d9f970816 100644
--- a/nixos/modules/services/security/simp_le.nix
+++ b/nixos/modules/services/security/simp_le.nix
@@ -145,8 +145,12 @@ in
         serviceConfig = {
           Type = "oneshot";
           SuccessExitStatus = [ "0" "1" ];
+          PermissionsStartOnly = true;
+          User = data.user;
+          Group = data.group;
+          PrivateTmp = true;
         };
-        path = [ pkgs.simp_le pkgs.sudo ];
+        path = [ pkgs.simp_le ];
         preStart = ''
           mkdir -p '${cfg.directory}'
           if [ ! -d '${cpath}' ]; then
@@ -157,13 +161,16 @@ in
         script = ''
           cd '${cpath}'
           set +e
-          sudo -u '${data.user}' -- simp_le ${concatMapStringsSep " " (arg: escapeShellArg (toString arg)) cmdline}
+          simp_le ${concatMapStringsSep " " (arg: escapeShellArg (toString arg)) cmdline}
           EXITCODE=$?
           set -e
-          if [ "$EXITCODE" = "0" ]; then
+          echo "$EXITCODE" > /tmp/lastExitCode
+          exit "$EXITCODE"
+        '';
+        postStop = ''
+          if [ -e /tmp/lastExitCode ] && [ "$(cat /tmp/lastExitCode)" = "0" ]; then
+            echo "Executing postRun hook..."
             ${data.postRun}
-          else
-            exit "$EXITCODE"
           fi
         '';
       })

From de24b00d41d6a80ccae0adecc3557c7c7154aa22 Mon Sep 17 00:00:00 2001
From: Franz Pletz <fpletz@fnordicwalking.de>
Date: Fri, 11 Dec 2015 17:42:17 +0100
Subject: [PATCH 6/9] nixos/simp_le: Rename to security.acme

---
 nixos/modules/module-list.nix                 |  2 +-
 .../simp_le.nix => security/acme.nix}         | 20 +++++++++----------
 2 files changed, 11 insertions(+), 11 deletions(-)
 rename nixos/modules/{services/security/simp_le.nix => security/acme.nix} (92%)

diff --git a/nixos/modules/module-list.nix b/nixos/modules/module-list.nix
index c708f095f40..039b562b6f3 100644
--- a/nixos/modules/module-list.nix
+++ b/nixos/modules/module-list.nix
@@ -80,6 +80,7 @@
   ./programs/xfs_quota.nix
   ./programs/zsh/zsh.nix
   ./rename.nix
+  ./security/acme.nix
   ./security/apparmor.nix
   ./security/apparmor-suid.nix
   ./security/ca.nix
@@ -388,7 +389,6 @@
   ./services/security/hologram.nix
   ./services/security/munge.nix
   ./services/security/physlock.nix
-  ./services/security/simp_le.nix
   ./services/security/torify.nix
   ./services/security/tor.nix
   ./services/security/torsocks.nix
diff --git a/nixos/modules/services/security/simp_le.nix b/nixos/modules/security/acme.nix
similarity index 92%
rename from nixos/modules/services/security/simp_le.nix
rename to nixos/modules/security/acme.nix
index 12d9f970816..72eac82defa 100644
--- a/nixos/modules/services/security/simp_le.nix
+++ b/nixos/modules/security/acme.nix
@@ -4,7 +4,7 @@ with lib;
 
 let
 
-  cfg = config.services.simp_le;
+  cfg = config.security.acme;
 
   certOpts = { ... }: {
     options = {
@@ -40,13 +40,13 @@ let
       user = mkOption {
         type = types.str;
         default = "root";
-        description = "User under which simp_le would run.";
+        description = "User running the ACME client.";
       };
 
       group = mkOption {
         type = types.str;
         default = "root";
-        description = "Group under which simp_le would run.";
+        description = "Group running the ACME client.";
       };
 
       postRun = mkOption {
@@ -95,9 +95,9 @@ in
   ###### interface
 
   options = {
-    services.simp_le = {
+    security.acme = {
       directory = mkOption {
-        default = "/var/lib/simp_le";
+        default = "/var/lib/acme";
         type = types.str;
         description = ''
           Directory where certs and other state will be stored by default.
@@ -138,9 +138,9 @@ in
                   ++ concatLists (mapAttrsToList (name: root: [ "-d" (if root == null then name else "${name}:${root}")]) data.extraDomains);
 
       in nameValuePair
-      ("simp_le-${cert}")
+      ("acme-${cert}")
       ({
-        description = "simp_le cert renewal for ${cert}";
+        description = "ACME cert renewal for ${cert} using simp_le";
         after = [ "network.target" ];
         serviceConfig = {
           Type = "oneshot";
@@ -177,13 +177,13 @@ in
     );
 
     systemd.timers = flip mapAttrs' cfg.certs (cert: data: nameValuePair
-      ("simp_le-${cert}")
+      ("acme-${cert}")
       ({
-        description = "timer for simp_le cert renewal of ${cert}";
+        description = "timer for ACME cert renewal of ${cert}";
         wantedBy = [ "timers.target" ];
         timerConfig = {
           OnCalendar = data.renewInterval;
-          Unit = "simp_le-${cert}.service";
+          Unit = "acme-simp_le-${cert}.service";
         };
       })
     );

From 0517d59a66f613471f478d0497aa5adb5dccfcdc Mon Sep 17 00:00:00 2001
From: Franz Pletz <fpletz@fnordicwalking.de>
Date: Sat, 12 Dec 2015 14:19:56 +0100
Subject: [PATCH 7/9] nixos/acme: Improve documentation

---
 nixos/modules/security/acme.nix | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/nixos/modules/security/acme.nix b/nixos/modules/security/acme.nix
index 72eac82defa..37e4c287623 100644
--- a/nixos/modules/security/acme.nix
+++ b/nixos/modules/security/acme.nix
@@ -21,14 +21,18 @@ let
 
       validMin = mkOption {
         type = types.int;
-        default = 2592000;
+        default = 30 * 24 * 3600;
         description = "Minimum remaining validity before renewal in seconds.";
       };
 
       renewInterval = mkOption {
         type = types.str;
         default = "weekly";
-        description = "Systemd calendar expression when to check for renewal. See systemd.time(7).";
+        description = ''
+          Systemd calendar expression when to check for renewal. See
+          <citerefentry><refentrytitle>systemd.time</refentrytitle>
+          <manvolnum>5</manvolnum></citerefentry>.
+        '';
       };
 
       email = mkOption {

From 9374ddb89523f6d77951445c5224b464d9ec198c Mon Sep 17 00:00:00 2001
From: Franz Pletz <fpletz@fnordicwalking.de>
Date: Sat, 12 Dec 2015 14:21:44 +0100
Subject: [PATCH 8/9] nixos/acme: validMin & renewInterval aren't cert-specific

---
 nixos/modules/security/acme.nix | 36 ++++++++++++++++-----------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/nixos/modules/security/acme.nix b/nixos/modules/security/acme.nix
index 37e4c287623..37de46cb1a5 100644
--- a/nixos/modules/security/acme.nix
+++ b/nixos/modules/security/acme.nix
@@ -19,22 +19,6 @@ let
         '';
       };
 
-      validMin = mkOption {
-        type = types.int;
-        default = 30 * 24 * 3600;
-        description = "Minimum remaining validity before renewal in seconds.";
-      };
-
-      renewInterval = mkOption {
-        type = types.str;
-        default = "weekly";
-        description = ''
-          Systemd calendar expression when to check for renewal. See
-          <citerefentry><refentrytitle>systemd.time</refentrytitle>
-          <manvolnum>5</manvolnum></citerefentry>.
-        '';
-      };
-
       email = mkOption {
         type = types.nullOr types.str;
         default = null;
@@ -108,6 +92,22 @@ in
         '';
       };
 
+      validMin = mkOption {
+        type = types.int;
+        default = 30 * 24 * 3600;
+        description = "Minimum remaining validity before renewal in seconds.";
+      };
+
+      renewInterval = mkOption {
+        type = types.str;
+        default = "weekly";
+        description = ''
+          Systemd calendar expression when to check for renewal. See
+          <citerefentry><refentrytitle>systemd.time</refentrytitle>
+          <manvolnum>5</manvolnum></citerefentry>.
+        '';
+      };
+
       certs = mkOption {
         default = { };
         type = types.loaOf types.optionSet;
@@ -136,7 +136,7 @@ in
     systemd.services = flip mapAttrs' cfg.certs (cert: data:
       let
         cpath = "${cfg.directory}/${cert}";
-        cmdline = [ "-v" "-d" cert "--default_root" data.webroot "--valid_min" data.validMin ]
+        cmdline = [ "-v" "-d" cert "--default_root" data.webroot "--valid_min" cfg.validMin ]
                   ++ optionals (data.email != null) [ "--email" data.email ]
                   ++ concatMap (p: [ "-f" p ]) data.plugins
                   ++ concatLists (mapAttrsToList (name: root: [ "-d" (if root == null then name else "${name}:${root}")]) data.extraDomains);
@@ -186,7 +186,7 @@ in
         description = "timer for ACME cert renewal of ${cert}";
         wantedBy = [ "timers.target" ];
         timerConfig = {
-          OnCalendar = data.renewInterval;
+          OnCalendar = cfg.renewInterval;
           Unit = "acme-simp_le-${cert}.service";
         };
       })

From 1685b9d06ebe93eaaed478bde02db813fc39e4b2 Mon Sep 17 00:00:00 2001
From: Franz Pletz <fpletz@fnordicwalking.de>
Date: Sat, 12 Dec 2015 16:06:24 +0100
Subject: [PATCH 9/9] nixos/acme: Add module documentation

---
 .../manual/configuration/configuration.xml    |   1 +
 nixos/doc/manual/default.nix                  |   1 +
 nixos/modules/security/acme.nix               | 121 +++++++++---------
 nixos/modules/security/acme.xml               |  69 ++++++++++
 4 files changed, 134 insertions(+), 58 deletions(-)
 create mode 100644 nixos/modules/security/acme.xml

diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml
index afffd60bc48..1e488b59343 100644
--- a/nixos/doc/manual/configuration/configuration.xml
+++ b/nixos/doc/manual/configuration/configuration.xml
@@ -26,6 +26,7 @@ effect after you run <command>nixos-rebuild</command>.</para>
 
 <!-- FIXME: auto-include NixOS module docs -->
 <xi:include href="postgresql.xml" />
+<xi:include href="acme.xml" />
 <xi:include href="nixos.xml" />
 
 <!-- Apache; libvirtd virtualisation -->
diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index 844cba57cd8..bd558dac971 100644
--- a/nixos/doc/manual/default.nix
+++ b/nixos/doc/manual/default.nix
@@ -55,6 +55,7 @@ let
       cp -prd $sources/* . # */
       chmod -R u+w .
       cp ${../../modules/services/databases/postgresql.xml} configuration/postgresql.xml
+      cp ${../../modules/security/acme.xml} configuration/acme.xml
       cp ${../../modules/misc/nixos.xml} configuration/nixos.xml
       ln -s ${optionsDocBook} options-db.xml
       echo "${version}" > version
diff --git a/nixos/modules/security/acme.nix b/nixos/modules/security/acme.nix
index 37de46cb1a5..8f3a2ee073b 100644
--- a/nixos/modules/security/acme.nix
+++ b/nixos/modules/security/acme.nix
@@ -131,67 +131,72 @@ in
   };
 
   ###### implementation
-  config = mkIf (cfg.certs != { }) {
+  config = mkMerge [
+    (mkIf (cfg.certs != { }) {
 
-    systemd.services = flip mapAttrs' cfg.certs (cert: data:
-      let
-        cpath = "${cfg.directory}/${cert}";
-        cmdline = [ "-v" "-d" cert "--default_root" data.webroot "--valid_min" cfg.validMin ]
-                  ++ optionals (data.email != null) [ "--email" data.email ]
-                  ++ concatMap (p: [ "-f" p ]) data.plugins
-                  ++ concatLists (mapAttrsToList (name: root: [ "-d" (if root == null then name else "${name}:${root}")]) data.extraDomains);
+      systemd.services = flip mapAttrs' cfg.certs (cert: data:
+        let
+          cpath = "${cfg.directory}/${cert}";
+          cmdline = [ "-v" "-d" cert "--default_root" data.webroot "--valid_min" cfg.validMin ]
+                    ++ optionals (data.email != null) [ "--email" data.email ]
+                    ++ concatMap (p: [ "-f" p ]) data.plugins
+                    ++ concatLists (mapAttrsToList (name: root: [ "-d" (if root == null then name else "${name}:${root}")]) data.extraDomains);
 
-      in nameValuePair
-      ("acme-${cert}")
-      ({
-        description = "ACME cert renewal for ${cert} using simp_le";
-        after = [ "network.target" ];
-        serviceConfig = {
-          Type = "oneshot";
-          SuccessExitStatus = [ "0" "1" ];
-          PermissionsStartOnly = true;
-          User = data.user;
-          Group = data.group;
-          PrivateTmp = true;
-        };
-        path = [ pkgs.simp_le ];
-        preStart = ''
-          mkdir -p '${cfg.directory}'
-          if [ ! -d '${cpath}' ]; then
-            mkdir -m 700 '${cpath}'
-            chown '${data.user}:${data.group}' '${cpath}'
-          fi
-        '';
-        script = ''
-          cd '${cpath}'
-          set +e
-          simp_le ${concatMapStringsSep " " (arg: escapeShellArg (toString arg)) cmdline}
-          EXITCODE=$?
-          set -e
-          echo "$EXITCODE" > /tmp/lastExitCode
-          exit "$EXITCODE"
-        '';
-        postStop = ''
-          if [ -e /tmp/lastExitCode ] && [ "$(cat /tmp/lastExitCode)" = "0" ]; then
-            echo "Executing postRun hook..."
-            ${data.postRun}
-          fi
-        '';
-      })
-    );
+        in nameValuePair
+        ("acme-${cert}")
+        ({
+          description = "ACME cert renewal for ${cert} using simp_le";
+          after = [ "network.target" ];
+          serviceConfig = {
+            Type = "oneshot";
+            SuccessExitStatus = [ "0" "1" ];
+            PermissionsStartOnly = true;
+            User = data.user;
+            Group = data.group;
+            PrivateTmp = true;
+          };
+          path = [ pkgs.simp_le ];
+          preStart = ''
+            mkdir -p '${cfg.directory}'
+            if [ ! -d '${cpath}' ]; then
+              mkdir -m 700 '${cpath}'
+              chown '${data.user}:${data.group}' '${cpath}'
+            fi
+          '';
+          script = ''
+            cd '${cpath}'
+            set +e
+            simp_le ${concatMapStringsSep " " (arg: escapeShellArg (toString arg)) cmdline}
+            EXITCODE=$?
+            set -e
+            echo "$EXITCODE" > /tmp/lastExitCode
+            exit "$EXITCODE"
+          '';
+          postStop = ''
+            if [ -e /tmp/lastExitCode ] && [ "$(cat /tmp/lastExitCode)" = "0" ]; then
+              echo "Executing postRun hook..."
+              ${data.postRun}
+            fi
+          '';
+        })
+      );
 
-    systemd.timers = flip mapAttrs' cfg.certs (cert: data: nameValuePair
-      ("acme-${cert}")
-      ({
-        description = "timer for ACME cert renewal of ${cert}";
-        wantedBy = [ "timers.target" ];
-        timerConfig = {
-          OnCalendar = cfg.renewInterval;
-          Unit = "acme-simp_le-${cert}.service";
-        };
-      })
-    );
+      systemd.timers = flip mapAttrs' cfg.certs (cert: data: nameValuePair
+        ("acme-${cert}")
+        ({
+          description = "timer for ACME cert renewal of ${cert}";
+          wantedBy = [ "timers.target" ];
+          timerConfig = {
+            OnCalendar = cfg.renewInterval;
+            Unit = "acme-simp_le-${cert}.service";
+          };
+        })
+      );
+    })
 
-  };
+    { meta.maintainers = with lib.maintainers; [ abbradar fpletz globin ];
+      meta.doc = ./acme.xml;
+    }
+  ];
 
 }
diff --git a/nixos/modules/security/acme.xml b/nixos/modules/security/acme.xml
new file mode 100644
index 00000000000..e32fa72c939
--- /dev/null
+++ b/nixos/modules/security/acme.xml
@@ -0,0 +1,69 @@
+<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-security-acme">
+
+<title>SSL/TLS Certificates with ACME</title>
+
+<para>NixOS supports automatic domain validation &amp; certificate
+retrieval and renewal using the ACME protocol. This is currently only
+implemented by and for Let's Encrypt. The alternative ACME client
+<literal>simp_le</literal> is used under the hood.</para>
+
+<section><title>Prerequisites</title>
+
+<para>You need to have a running HTTP server for verification. The server must
+have a webroot defined that can serve
+<filename>.well-known/acme-challenge</filename>. This directory must be
+writeable by the user that will run the ACME client.</para>
+
+<para>For instance, this generic snippet could be used for Nginx:
+
+<programlisting>
+http {
+  server {
+    server_name _;
+    listen 80;
+    listen [::]:80;
+
+    location /.well-known/acme-challenge {
+      root /var/www/challenges;
+    }
+
+    location / {
+      return 301 https://$host$request_uri;
+    }
+  }
+}
+</programlisting>
+</para>
+
+</section>
+
+<section><title>Configuring</title>
+
+<para>To enable ACME certificate retrieval &amp; renewal for a certificate for
+<literal>foo.example.com</literal>, add the following in your
+<filename>configuration.nix</filename>:
+
+<programlisting>
+security.acme.certs."foo.example.com" = {
+  webroot = "/var/www/challenges";
+  email = "foo@example.com";
+};
+</programlisting>
+</para>
+
+<para>The private key <filename>key.pem</filename> and certificate
+<filename>fullchain.pem</filename> will be put into
+<filename>/var/lib/acme/foo.example.com</filename>. The target directory can
+be configured with the option <literal>security.acme.directory</literal>.
+</para>
+
+<para>Refer to <xref linkend="ch-options" /> for all available configuration
+options for the <literal>security.acme</literal> module.</para>
+
+</section>
+
+</chapter>