(gnu services certbot) module provides a service 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
Let’s Encrypt provides the
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
The 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, the automated periodic renewals, and the deployment tasks associated with the renewal (e.g. reloading services, copying keys with different permissions).
Certbot is run twice a day, at a random minute within the hour. It won’t do anything until your certificates are due for renewal or revoked, but running it regularly would give your service a chance of staying online in case a Let’s Encrypt-initiated revocation happened for some reason.
By using this service, you agree to the ACME Subscriber Agreement, which can be found there: https://acme-v01.api.letsencrypt.org/directory.
A service type for the
certbot Let’s Encrypt client. Its value
must be a
certbot-configuration record as in this example:
(define %nginx-deploy-hook (program-file "nginx-deploy-hook" #~(let ((pid (call-with-input-file "/var/run/nginx/pid" read))) (kill pid SIGHUP)))) (service certbot-service-type (certbot-configuration (email "email@example.com") (certificates (list (certificate-configuration (domains '("example.net" "www.example.net")) (deploy-hook %nginx-deploy-hook)) (certificate-configuration (domains '("bar.example.net")))))))
See below for details about
Data type representing the configuration of the
This type has the following parameters:
The certbot package to use.
The directory from which to serve the Let’s Encrypt challenge/response files.
A list of
certificates-configurations for which to generate
certificates and request signatures. Each certificate has a
Optional email address used for registration and recovery contact. Setting this is encouraged as it allows you to receive important notifications about the account and issued certificates.
Optional URL of ACME server. Setting this overrides certbot’s default, which is the Let’s Encrypt server.
Size of the RSA key.
default-location(default: see below)
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
service with an
nginx-server-configuration listening on the
domains on port 80, and which has a
nginx-location-configuration for the
path subspace used by Let’s Encrypt. See Web Services, for more on
these nginx configuration data types.
Requests to other URL paths will be matched by the
default-location, which if present is added to all
By default, the
default-location will issue a redirect from
you to define what to serve on your site via
#f to not issue a default location.
Data type representing the configuration of a certificate. This type has the following parameters:
name(default: see below)
This name is used by Certbot for housekeeping and in file paths; it
doesn’t affect the content of the certificate itself. To see
certificate names, run
Its default is the first provided domain.
The first domain provided will be the subject CN of the certificate, and all domains will be Subject Alternative Names on the certificate.
The challenge type that has to be run by certbot. If
#f is specified,
default to the HTTP challenge. If a value is specified, defaults to the
manual plugin (see
the documentation at https://certbot.eff.org/docs/using.html#hooks),
and gives Let’s Encrypt permission to log the public IP address of the
Command to be run in a shell once for each certificate challenge to be
answered. For this command, the shell variable
will contain the domain being authenticated,
contains the validation string and
$CERTBOT_TOKEN contains the
file name of the resource requested when performing an HTTP-01 challenge.
Command to be run in a shell once for each certificate challenge that
have been answered by the
auth-hook. For this command, the shell
variables available in the
auth-hook script are still available, and
$CERTBOT_AUTH_OUTPUT will contain the standard output
Command to be run in a shell once for each successfully issued
certificate. For this command, the shell variable
$RENEWED_LINEAGE will point to the config live subdirectory (for
example, ‘"/etc/letsencrypt/live/example.com"’) containing the new
certificates and keys; the shell variable
contain a space-delimited list of renewed certificate domains (for
example, ‘"example.com www.example.com"’.
certificate-configuration, the certificate is saved to
/etc/letsencrypt/live/name/fullchain.pem and the key is