diff options
| -rw-r--r-- | doc/guix.texi | 80 | ||||
| -rw-r--r-- | gnu/local.mk | 1 | ||||
| -rw-r--r-- | gnu/services/certbot.scm | 128 |
3 files changed, 209 insertions, 0 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 0d334e302f..21b6d7d886 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -215,6 +215,7 @@ Services * Messaging Services:: Messaging services. * Kerberos Services:: Kerberos services. * Web Services:: Web servers. +* Certificate Services:: TLS certificates via Let's Encrypt. * VPN Services:: VPN daemons. * Network File System:: NFS related services. * Continuous Integration:: The Cuirass service. @@ -8605,6 +8606,7 @@ declaration. * Messaging Services:: Messaging services. * Kerberos Services:: Kerberos services. * Web Services:: Web servers. +* Certificate Services:: TLS certificates via Let's Encrypt. * VPN Services:: VPN daemons. * Network File System:: NFS related services. * Continuous Integration:: The Cuirass service. @@ -13379,6 +13381,84 @@ Whether the server should add its configuration to response. @end table @end deftp + +@node Certificate Services +@subsubsection Certificate Services + +@cindex web +@cindex www +@cindex HTTP +The @code{(gnu services certbot)} module allows Guix systems to +automatically obtain a valid TLS certificate from the Let's Encrypt +certificate authority. These certificates can then be used to serve +content securely over HTTPS or other TLS-based protocols, with the +knowledge that the client will be able to verify the server's +authenticity. + +Let's Encrypt (@url{https://letsencrypt.org/}) provides the +@code{certbot} tool to automate the certification process. This tool +first securely generates a key on the server. It then makes a request +to the Let's Encrypt certificate authority (CA) to sign the key. The CA +checks that the request originates from the host in question by using a +challenge-response protocol, requiring the server to provide its +response over HTTP. If that protocol completes successfully, the CA +signs the key, resulting in a certificate. That certificate is valid +for a limited period of time, and therefore to continue to provide TLS +services, the server needs to periodically ask the CA to renew its +signature. + +The Guix certbot service automates this process: the initial key +generation, the initial certification request to the Let's Encrypt +service, the web server challenge/response integration, writing the +certificate to disk, and the automated periodic renewals. + +@defvr {Scheme Variable} certbot-service-type +A service type for the @code{certbot} Let's Encrypt client. +@end defvr + +@deftp {Data Type} certbot-configuration +Data type representing the configuration of the @code{certbot} serice. +This type has the following parameters: +@table @asis +@item @code{package} (default: @code{certbot}) +The certbot package to use. + +@item @code{webroot} (default: @code{/var/www}) +The directory from which to serve the Let's Encrypt challenge/response +files. + +@item @code{hosts} (default: @code{()}) +A list of hosts for which to generate certificates and request +signatures. + +@item @code{default-location} (default: @i{see below}) +The default @code{nginx-location-configuration}. Because @code{certbot} +needs to be able to serve challenges and responses, it needs to be able +to run a web server. It does so by extending the @code{nginx} web +service with an @code{nginx-server-configuration} listening on the +@var{hosts} on port 80, and which has a +@code{nginx-location-configuration} for the @code{/.well-known/} URI +path subspace used by Let's Encrypt. @xref{Web Services}, for more on +these nginx configuration data types. + +Requests to other URL paths will be matched by the +@code{default-location}, which if present is added to all +@code{nginx-server-configuration}s. + +By default, the @code{default-location} will issue a redirect from +@code{http://@var{host}/...} to @code{https://@var{host}/...}, leaving +you to define what to serve on your site via @code{https}. + +Pass @code{#f} to not issue a default location. +@end table +@end deftp + +The public key and its signatures will be written to +@code{/etc/letsencrypt/live/@var{host}/fullchain.pem}, for each +@var{host} in the configuration. The private key is written to +@code{/etc/letsencrypt/live/@var{host}/privkey.pem}. + + @node VPN Services @subsubsection VPN Services @cindex VPN (virtual private network) diff --git a/gnu/local.mk b/gnu/local.mk index 31239933ce..ac0c9d510d 100644 --- a/gnu/local.mk +++ b/gnu/local.mk @@ -414,6 +414,7 @@ GNU_SYSTEM_MODULES = \ %D%/services/admin.scm \ %D%/services/avahi.scm \ %D%/services/base.scm \ + %D%/services/certbot.scm \ %D%/services/configuration.scm \ %D%/services/cuirass.scm \ %D%/services/cups.scm \ diff --git a/gnu/services/certbot.scm b/gnu/services/certbot.scm new file mode 100644 index 0000000000..c11c9a66bd --- /dev/null +++ b/gnu/services/certbot.scm @@ -0,0 +1,128 @@ +;;; GNU Guix --- Functional package management for GNU +;;; Copyright © 2016 ng0 <ng0@we.make.ritual.n0.is> +;;; Copyright © 2016 Sou Bunnbu <iyzsong@member.fsf.org> +;;; +;;; This file is part of GNU Guix. +;;; +;;; GNU Guix is free software; you can redistribute it and/or modify it +;;; under the terms of the GNU General Public License as published by +;;; the Free Software Foundation; either version 3 of the License, or (at +;;; your option) any later version. +;;; +;;; GNU Guix is distributed in the hope that it will be useful, but +;;; WITHOUT ANY WARRANTY; without even the implied warranty of +;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;;; GNU General Public License for more details. +;;; +;;; You should have received a copy of the GNU General Public License +;;; along with GNU Guix. If not, see <http://www.gnu.org/licenses/>. + +(define-module (gnu services certbot) + #:use-module (gnu services) + #:use-module (gnu services base) + #:use-module (gnu services shepherd) + #:use-module (gnu services mcron) + #:use-module (gnu services web) + #:use-module (gnu system shadow) + #:use-module (gnu packages tls) + #:use-module (guix records) + #:use-module (guix gexp) + #:use-module (srfi srfi-1) + #:use-module (ice-9 match) + #:export (certbot-service-type + certbot-configuration + certbot-configuration?)) + +;;; Commentary: +;;; +;;; Automatically obtaining TLS certificates from Let's Encrypt. +;;; +;;; Code: + + +(define-record-type* <certbot-configuration> + certbot-configuration make-certbot-configuration + certbot-configuration? + (package certbot-configuration-package + (default certbot)) + (webroot certbot-configuration-webroot + (default "/var/www")) + (hosts certbot-configuration-hosts + (default '())) + (default-location certbot-configuration-default-location + (default + (nginx-location-configuration + (uri "/") + (body + (list "return 301 https://$host$request_uri;")))))) + +(define certbot-renewal-jobs + (match-lambda + (($ <certbot-configuration> package webroot hosts default-location) + (match hosts + ;; Avoid pinging certbot if we have no hosts. + (() '()) + (_ + (list + ;; Attempt to renew the certificates twice a week. + #~(job (lambda (now) + (next-day-from (next-hour-from now '(3)) + '(2 5))) + (string-append #$package "/bin/certbot renew" + (string-concatenate + (map (lambda (host) + (string-append " -d " host)) + #$hosts)))))))))) + +(define certbot-activation + (match-lambda + (($ <certbot-configuration> package webroot hosts default-location) + (with-imported-modules '((guix build utils)) + #~(begin + (use-modules (guix build utils)) + (mkdir-p #$webroot) + (for-each + (lambda (host) + (unless (file-exists? (in-vicinity "/etc/letsencrypt/live" host)) + (unless (zero? (system* + (string-append #$certbot "/bin/certbot") + "certonly" "--webroot" "-w" #$webroot + "-d" host)) + (error "failed to acquire cert for host" host)))) + '#$hosts)))))) + +(define certbot-nginx-server-configurations + (match-lambda + (($ <certbot-configuration> package webroot hosts default-location) + (map + (lambda (host) + (nginx-server-configuration + (http-port 80) + (https-port #f) + (ssl-certificate #f) + (ssl-certificate-key #f) + (server-name (list host)) + (locations + (filter identity + (list + (nginx-location-configuration + (uri "/.well-known") + (body (list (list "root " webroot ";")))) + default-location))))) + hosts)))) + +(define certbot-service-type + (service-type (name 'certbot) + (extensions + (list (service-extension nginx-service-type + certbot-nginx-server-configurations) + (service-extension activation-service-type + certbot-activation) + (service-extension mcron-service-type + certbot-renewal-jobs))) + (compose concatenate) + (extend (lambda (config additional-hosts) + (certbot-configuration + (inherit config) + (hosts (append (certbot-configuration-hosts config) + additional-hosts))))))) |