The (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 authenticity.
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 signature.
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 "foo@example.net") (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 certbot-configuration.
Data type representing the configuration of the certbot service.
This type has the following parameters:
package (default: certbot)The certbot package to use.
webroot (default: /var/www)The directory from which to serve the Let’s Encrypt challenge/response files.
certificates (default: ())A list of certificates-configurations for which to generate
certificates and request signatures. Each certificate has a name and
several domains.
email (default: #f)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.
server (default: #f)Optional URL of ACME server. Setting this overrides certbot’s default, which is the Let’s Encrypt server.
rsa-key-size (default: 2048)Size of the RSA key.
default-location (default: see below)The default nginx-location-configuration. Because 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 nginx web service with
an nginx-server-configuration listening on the domains on port
80, and which has a nginx-location-configuration for the
/.well-known/ URI path subspace used by Let’s Encrypt. See Web服务, 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 nginx-server-configurations.
By default, the default-location will issue a redirect from
http://domain/... to https://domain/..., leaving
you to define what to serve on your site via https.
Pass #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
certbot certificates.
Its default is the first provided domain.
domains (default: ())The first domain provided will be the subject CN of the certificate, and all domains will be Subject Alternative Names on the certificate.
challenge（默认值：#f）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 authentication-hook, cleanup-hook
and 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 requesting machine.
csr (default: #f)File name of Certificate Signing Request (CSR) in DER or PEM format. If
#f is specified, this argument will not be passed to certbot. If a
value is specified, certbot will use it to obtain a certificate, instead of
using a self-generated CSR. The domain-name(s) mentioned in domains,
must be consistent with the domain-name(s) mentioned in CSR file.
authentication-hook（默认值：#f）Command to be run in a shell once for each certificate challenge to be
answered. For this command, the shell variable $CERTBOT_DOMAIN will
contain the domain being authenticated, $CERTBOT_VALIDATION contains
the validation string and $CERTBOT_TOKEN contains the file name of
the resource requested when performing an HTTP-01 challenge.
cleanup-hook（默认值：#f）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
additionally $CERTBOT_AUTH_OUTPUT will contain the standard output of
the auth-hook script.
deploy-hook (default: #f)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 $RENEWED_DOMAINS will contain a
space-delimited list of renewed certificate domains (for example,
‘"example.com www.example.com"’.
For each certificate-configuration, the certificate is saved to
/etc/letsencrypt/live/name/fullchain.pem and the key is saved
to /etc/letsencrypt/live/name/privkey.pem.