ja:Certbot ru:Certbot Certbot is Electronic Frontier Foundation's ACME client, which is written in Python and provides conveniences like automatic web server configuration and a built-in webserver for the HTTP challenge. Certbot is recommended by Let's Encrypt.

Installation

Install the certbot package.

Plugins are available for automated configuration and installation of the issued certificates in web servers:

• The Nginx plugin can be installed with the certbot-nginx package.

• The Apache HTTP Server plugin can be installed with the certbot-apache package.

Configuration

Consult the Certbot documentation for more information about creation and usage of certificates.

Plugins

Nginx

The plugin certbot-nginx provides an automatic configuration for nginx. This plugin will try to detect the configuration setup for each domain. The plugin adds extra configuration recommended for security, settings for certificate use, and paths to Certbot certificates. See #Managing Nginx server blocks for examples.

First time setup of server-blocks:

# certbot --nginx

To renew certificates:

# certbot renew

To change certificates without modifying nginx configuration files:

# certbot --nginx certonly

See Certbot-Nginx on Arch Linux for more information and #Automatic renewal to keep installed certificates valid.

Managing Nginx server blocks

The following example may be used in all server blocks when managing these files manually:

server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2; # Listen on IPv6
  ssl_certificate /etc/letsencrypt/live/domain/fullchain.pem; # managed by Certbot
  ssl_certificate_key /etc/letsencrypt/live/domain/privkey.pem; # managed by Certbot
  include /etc/letsencrypt/options-ssl-nginx.conf;
  ..
}

/etc/nginx/sites-available/example

See nginx#TLS for more information.

It is also possible to create a separated configuration file and include it in each server block:

ssl_certificate /etc/letsencrypt/live/domain/fullchain.pem; # managed by Certbot
ssl_certificate_key /etc/letsencrypt/live/domain/privkey.pem; # managed by Certbot
include /etc/letsencrypt/options-ssl-nginx.conf;

/etc/nginx/conf/001-certbot.conf

server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2; # Listen on IPv6
  include conf/001-certbot.conf;
  ..
}

/etc/nginx/sites-available/example

Apache

The plugin certbot-apache provides an automatic configuration for the Apache HTTP Server. This plugin will try to detect the configuration setup for each domain. The plugin adds extra configuration recommended for security, settings for certificate use, and paths to Certbot certificates. See #Managing Apache virtual hosts for examples.

First time setup of virtual hosts:

# certbot --apache

To renew certificates:

# certbot renew

To change certificates without modifying Apache configuration files:

# certbot --apache certonly

See Certbot-Apache on Arch Linux for more information and #Automatic renewal to keep installed certificates valid.

Managing Apache virtual hosts

The following example may be used in all virtual hosts when managing these files manually:

<IfModule mod_ssl.c>
<VirtualHost *:443>

Include /etc/letsencrypt/options-ssl-apache.conf
SSLCertificateFile /etc/letsencrypt/live/'domain'/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/'domain'/privkey.pem

</VirtualHost>
</IfModule>

/etc/httpd/conf/extra/001-certbot.conf

When the VirtualHost above is automatically generated by certbot-apache, it looks like sometimes the 'Include' line may appear after the two 'SSLCertificate' lines. When this is the case, accessing the virtualHost from a browser using http wont work with an error SSL_PROTOCOL_ERROR. If this happens, simply put the Include line above the two SSLCertificates lines and restart httpd.

  <IfModule mod_ssl.c>
  Listen 443
  </IfModule>

  Include conf/extra/001-certbot.conf
  ..

/etc/httpd/conf/httpd.conf

See Apache HTTP Server#TLS for more information.

PKCS#12

The plugin python-certbot-pkcs12 provides an automatic installation with PKCS#12 certificates archive, which is mostly used by Kestrel

The following command install PKCS#12 archive to your destination only:

# certbot install -i pkcs12 --pkcs12-location /etc/locationToPlaceFile.pfx

To integrate with other commands:

# certbot some_options --installer pkcs12 --pkcs12-location /path/to/your/pkcs12.p12

This integrates installer option with your previous operation by writing options into certbot configuration, and should be auto applied when renewal:

# certbot renew

Webroot

When using the webroot method the Certbot client places a challenge response inside /path/to/domain.tld/html/.well-known/acme-challenge/ which is used for validation.

The use of this method is recommended over a manual install; it offers automatic renewal and easier certificate management. However the usage of #Plugins may be the preferred since it allows automatic configuration and installation.

Mapping ACME-challenge requests

Management of can be made easier by mapping all HTTP-requests for .well-known/acme-challenge to a single folder, e.g. /var/lib/letsencrypt.

The path has then to be writable for Cerbot and the web server (e.g. nginx or Apache HTTP Server running as user http):

# mkdir -p /var/lib/letsencrypt/.well-known
# chgrp http /var/lib/letsencrypt
# chmod g+s /var/lib/letsencrypt

nginx

Create a file containing the location block and include this inside a server block:

location ^~ /.well-known/acme-challenge/ {
  allow all;
  root /var/lib/letsencrypt/;
  default_type "text/plain";
  try_files $uri =404;
}

/etc/nginx/conf.d/letsencrypt.conf

Example of a server configuration:

server {
  server_name domain.tld
   ..
  include conf.d/letsencrypt.conf;
}

/etc/nginx/servers-available/domain.conf

Apache

Create the file /etc/httpd/conf/extra/httpd-acme.conf:

Alias /.well-known/acme-challenge/ "/var/lib/letsencrypt/.well-known/acme-challenge/"
<Directory "/var/lib/letsencrypt/">
    AllowOverride None
    Options MultiViews SymLinksIfOwnerMatch IncludesNoExec
    Require method GET POST OPTIONS
</Directory>

/etc/httpd/conf/extra/httpd-acme.conf

Including this in /etc/httpd/conf/httpd.conf:

Include conf/extra/httpd-acme.conf

/etc/httpd/conf/httpd.conf

Obtain certificate(s)

Request a certificate for domain.tld using /var/lib/letsencrypt/ as public accessible path:

# certbot certonly --email email@example.com --webroot -w /var/lib/letsencrypt/ -d domain.tld

To add a (sub)domain, include all registered domains used on the current setup:

# certbot certonly --email email@example.com --webroot -w /var/lib/letsencrypt/ -d domain.tld,sub.domain.tld

To renew (all) the current certificate(s):

# certbot renew

See #Automatic renewal as alternative approach.

Manual

If there is no plugin for your web server, use the following command:

# certbot certonly --manual

When preferring to use DNS challenge (TXT record) use:

# certbot certonly --manual --preferred-challenges dns

This will automatically verify your domain and create a private key and certificate pair. These are placed in /etc/letsencrypt/archive/your.domain/ and symlinked from /etc/letsencrypt/live/your.domain/.

You can then manually configure your web server to reference the private key, certificate and full certificate chain in the symlinked directory.

DNS challenge

For servers which are not exposed to public internet, DNS-01 challenge can be used to verify domain ownership

Install the certbot plugin for your dns provider certbot-dns-*. Below example shows for cloudflare using certbot-dns-cloudflare.

Create a Credential file

dns_cloudflare_api_token = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

/etc/certbot-cloudflare.creds.ini

Get certificate.

# chmod 600 /etc/certbot-cloudflare.creds.ini
# certbot certonly --dns-cloudflare --dns-cloudflare-credentials /etc/certbot-cloudflare.creds.ini -d domain.tld

certbot-renew.service will renew automatically using the above credential file #Automatic renewal. See docs for obtaining api token and other options.

Advanced configuration

Automatic renewal

systemd

certbot comes with a systemd certbot-renew.service, which attempts to renew certificates that expire in less than 30 days. If all certificates are not due for renewal, this service does nothing.

If you do not use a plugin to manage the web server configuration automatically, the web server has to be reloaded manually to reload the certificates each time they are renewed. This can be done by adding --post-hook "systemctl reload nginx.service" to the ExecStart command https://certbot.eff.org/docs/using.html#renewing-certificates. Of course use httpd.service instead of nginx.service if appropriate. Additional services can be added to the systemctl command as needed, e.g. systemctl reload httpd dovecot postfix.

Enable and start certbot-renew.timer to check for certificate renewal twice a day, including a randomized delay so that everyone's requests for renewal will be spread over the day to lighten the Let's Encrypt server load https://certbot.eff.org/#arch-nginx.

Automatic renewal for wildcard certificates

The process is fairly simple. To issue a wildcard certificate, you have to do it via a DNS challenge request, using the ACMEv2 protocol.

While issuing a certificate manually is easy, it is not straight forward for automation. The DNS challenge represents a TXT record, given by certbot, which has to be set manually in the domain zone file.

You will need to update the zone file upon every renew. To avoid doing that manually, you may use RFC 2136 for which certbot has a plugin packaged in certbot-dns-rfc2136. You will also need to configure your DNS server to allow dynamic updates for TXT records.

Configure BIND for rfc2136

Generate a TSIG secret key:

$ tsig-keygen -a HMAC-SHA512 example-key

and add it in the configuration file:

...
zone "domain.ltd" IN {
        ...
        // this is for certbot
        update-policy {
                grant example-key name _acme-challenge.domain.ltd. txt;
        };
        ...
};

key "example-key" {
        algorithm hmac-sha512;
        secret "a_secret_key";
};
...

/etc/named.conf

Restart named.service.

Configure certbot for rfc2136

Install certbot-dns-rfc2136, then create a configuration file for it.

dns_rfc2136_server = IP.ADD.RE.SS
dns_rfc2136_name = example-key
dns_rfc2136_secret = INSERT_KEY_WITHOUT_QUOTES
dns_rfc2136_algorithm = HMAC-SHA512

/etc/letsencrypt/rfc2136.ini

Since the file contains a copy of the secret key, secure it with chmod by removing the group and others permissions.

Test what we did:

# certbot certonly --dns-rfc2136 --force-renewal --dns-rfc2136-credentials /etc/letsencrypt/rfc2136.ini --server https://acme-v02.api.letsencrypt.org/directory --email example@domain.ltd --agree-tos --no-eff-email -d 'domain.ltd' -d '*.domain.ltd'

If you pass the validation successfully and receive certificates, then you are good to go with automating certbot. Otherwise, something went wrong and you need to debug your setup. It basically boils down to running certbot renew from now on, see #Automatic renewal.

See also

• Acme.sh alternative ACME client supporting Let's Encrypt

• Transport Layer Security#ACME clients

• EFF's Certbot documentation

• Let's Encrypt – List of ACME clients