services: certbot: Add dry-run? certificate option.

* gnu/services/certbot.scm (certificate-configuration): Add dry-run? field.
(certbot-command): Use it to pass --dry-run to certbot.
* doc/guix.texi (Certificate Services): Document dry-run? option.

Change-Id: I26b0dc06e2b7e5fb34305deee09e311d085f8a4b
Signed-off-by: Maxim Cournoyer <maxim@guixotic.coop>
Modified-by: Maxim Cournoyer <maxim@guixotic.coop>

1 files changed, 35 insertions, 0 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 0b4c3ceac6d..d03924ea967 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -35816,6 +35816,41 @@ certificates and keys; the shell variable @code{$RENEWED_DOMAINS} will
 contain a space-delimited list of renewed certificate domains (for
 example, @samp{"example.com www.example.com"}.
 
+@item @code{dry-run?} (default: @code{#f})
+Communicate with the ACME server but do not update certificates nor
+trigger @code{deploy-hook}.  This is useful as a temporary setting to
+test the challenge procedure, especially the @code{authentication-hook}
+and @code{cleanup-hook} while working on them.  It's also a good idea to
+use the Let's Encrypt staging server at
+@url{https://acme-staging-v02.api.letsencrypt.org/directory} while
+testing, which allows for higher rate limits, but with which
+@code{certbot} will helpfully refuse to update certificates and
+recommend the @code{dry-run?} option.  For example:
+
+@lisp
+(define %authentication-hook
+  (program-file "authentication-hook"
+    #~(let ((domain (getenv "CERTBOT_DOMAIN"))
+            (token (getenv "CERTBOT_TOKEN")))
+        (format #t "Hey, can you authenticate ~a with ~a for me?"
+                domain token))))
+
+(define %cleanup-hook
+  (program-file "authentication-hook"
+    #~(display "Bye")))
+
+(service certbot-service-type
+         (certbot-configuration
+          (server "https://acme-staging-v02.api.letsencrypt.org/directory")
+          (certificates
+           (list
+            (certificate-configuration
+              (dry-run? #t)
+              (authentication-hook %authentication-hook)
+              (cleanup-hook %cleanup-hook)
+              (domains '("example.net" "www.example.net")))))))
+@end lisp
+
 @item @code{start-self-signed?} (default: @code{#t})
 Whether to generate an initial self-signed certificate during system
 activation.  This option is particularly useful to allow @code{nginx} to