Certbot

From ArchWiki
Revision as of 17:04, 6 January 2017 by Francoism (talk | contribs) (→‎Configuration: more info instead)
Jump to navigation Jump to search

Let’s Encrypt is a free, automated, and open certificate authority utilizing the ACME protocol.

The official client is called Certbot, which allows to request valid X.509 certificates straight from the command line. A minimal client with manual CSR creation is available at acme-tinyAUR, clients suitable for scripts are simp_le-gitAUR and letsencrypt-cliAUR.

Certbot, previously called the Let’s Encrypt client, is the official reference client. It is written in Python and provides a command-line tool to obtain certificates. Given instructions are applied to the official Let's Encrypt client.

Installation

Install the certbot package.

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

Configuration

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

Webroot

Note:
  • For Apache use --apache or --nginx for Nginx instead of --webroot.
  • The webserver and domain should be proper configured and accessible over HTTP to the internet.
  • Permissions may need to be altered on the host to allow read-access to http://domain.tld/.well-know.

When using the webroot method, the Certbot client places a challenge response inside /path/to/domain.tld/html/.well-known/acme-challenge/.

The use of this method is recommend over a manual install; it offers automatically renewal and easier certificate management.

Obtain/renew certificate

Request a certificate for domain.tld using /path/to/domain.tld/html/ as public accessible path:

# certbot certonly --email email@example.com --webroot -w /path/to/domain.tld/html/ -d domain.tld

Manual

Note:
  • The running webserver has to temporarily stopped.
  • Automatically renewal is not available when performing manual installation, see #Webroot instead.

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/live/your.domain/.

You can then manually configure your web server to use the key and certificate in that directory.

Note: Running this command multiple times will create multiple sets of files with a trailing number in /etc/letsencrypt/live/your.domain/ so take care to rename them in that directory or in the webserver config file.

Advanced Configuration

Multiple domains

If you use more than one domain or subdomains, the webroot has to be given for every domain. If no new webroot is given, the previous value is used.

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 the Let's Encrypt client and the web server (e.g. nginx or Apache running as user http):

# chgrp http /var/lib/letsencrypt
# chmod g+s /var/lib/letsencrypt

Nginx

Create a file containing the location block and include this in server blocks of servers:

/etc/nginx/conf/letsencrypt.conf

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

Example of a server configuration:

/etc/nginx/servers-available/domain.conf
server {
  server_name domain.tld
   ..
  include conf/letsencrypt.conf;
}

Apache

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

/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 Indexes SymLinksIfOwnerMatch IncludesNoExec
    Require method GET POST OPTIONS
</Directory>

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

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

Automatic renewal

When running certbot certonly, Certbot stores the domains and webroot directories in /etc/letsencrypt/renewal, so the certificates can be renewed later automatically by running certbot renew.

systemd

You can fully automate this by creating a systemd service. Be sure to add an #Automatic renewal timer after creating the service.

/etc/systemd/system/certbot.service
[Unit]
Description=Let's Encrypt renewal

[Service]
Type=oneshot
ExecStart=/usr/bin/certbot renew --quiet --agree-tos
Webservers

When using the standalone method you'll want to stop your webserver before executing the renew request and start your webserver when certbot is finished, luckily certbot provides some hooks that do just that.

Nginx
/etc/systemd/system/certbot.service
[Unit]
Description=Let's Encrypt renewal

[Service]
Type=oneshot
ExecStart=/usr/bin/certbot renew --pre-hook "/usr/bin/systemctl stop nginx.service" --post-hook "/usr/bin/systemctl start nginx.service" --quiet --agree-tos
Apache
/etc/systemd/system/certbot.service
[Unit]
Description=Let's Encrypt renewal

[Service]
Type=oneshot
ExecStart=/usr/bin/certbot renew --pre-hook "/usr/bin/systemctl stop httpd.service" --post-hook "/usr/bin/systemctl start httpd.service" --quiet --agree-tos
Automatic renewal timer

Before adding a timer, check that the service is working correctly and is not trying to prompt anything. Then, you can add a timer to renew the certificates daily. Include a randomized delay so that everyone's requests for renewal will be evenly spread over the day to lighten the Let's Encrypt server load.

/etc/systemd/system/certbot.timer
[Unit]
Description=Daily renewal of Let's Encrypt's certificates

[Timer]
OnCalendar=daily
RandomizedDelaySec=1day
Persistent=true

[Install]
WantedBy=timers.target

Enable and start certbot.timer.

You'll probably want your web server to reload the certificates after each time they're renewed. You can realize that by adding one of these lines to the certbot.service file:

  • Apache: ExecStartPost=/bin/systemctl reload httpd.service
  • nginx: ExecStartPost=/bin/systemctl reload nginx.service

See also