Difference between revisions of "Certbot"

From ArchWiki
Jump to: navigation, search
(Undo revision 519835 by Relmir (talk) - this is the same path as used in #Obtain certificate(s) for the --webroot parameter)
m (Larivact moved page Let’s Encrypt to Let's Encrypt over redirect: replace Unicode quotation mark with ASCII equivalent)
(One intermediate revision by the same user not shown)
Line 198: Line 198:
== See also ==
== See also ==
* [[Wikipedia:Let's Encrypt|Wikipedia article]]
* [https://certbot.eff.org/ EFF's Certbot documentation]
* [https://certbot.eff.org/ EFF's Certbot documentation]
* [https://letsencrypt.org/docs/client-options/ List of ACME clients]
* [https://letsencrypt.org/docs/client-options/ List of ACME clients]

Revision as of 05:16, 14 May 2018

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

It is recommended to start with the certbot client, which allows to request valid X.509 certificates straight from the command line.

If you would like to try other clients, a minimal client with manual certificate signing request (CSR) creation is available at acme-tiny. Clients suitable for scripts are simp_le-gitAUR and letsencrypt-cliAUR.


Install the certbot package.

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


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

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: Explain what the Nginx (# certbot --nginx) and Apache plugins actually do and how they modify the webserver configuration. So far this section targets only the #Webroot and #Manual ways. (Discuss in Talk:Certbot#)


Warning: Configuration files may be rewritten when using a plugin. Creating a backup first is recommended.


The plugin certbot-nginx provides an automatic configuration for nginx server-blocks:

# certbot --nginx

To renew certificates:

# certbot renew

To change certificates without modifying nginx config files:

# certbot --nginx certonly

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

Managing server blocks

The following example may be used in each 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;
  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

See nginx#TLS/SSL for more information.

It's also possible to create a separated config 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;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2; # Listen on IPv6
  include conf/001-certbot.conf;


  • The Webroot method requires HTTP on port 80 for Certbot to validate.
  • The Server Name must match that of it's corresponding DNS.
  • Permissions may need to be altered on the host to allow read-access to http://domain.tld/.well-known.

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 recommend 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

Tango-inaccurate.pngThe factual accuracy of this article or section is disputed.Tango-inaccurate.png

Reason: In the webroot way, the /var/lib/letsencrypt path is dictated by certbot. Manual creation is not necessary, that applies to #Manual. (Discuss in Talk:Certbot#)

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 running as user http):

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

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;

Example of a server configuration:

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

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

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

Include conf/extra/httpd-acme.conf

Obtain certificate(s)

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: detail lacking to successfully accomplish task being taught (Discuss in Talk:Certbot#accuracy_flag)

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.


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.

Note: Running this command multiple times, or renewing certificates will create multiple sets of files with a trailing number in /etc/letsencrypt/archive/your.domain/. Certbot automatically updates the symlinks in /etc/letsencrypt/live/your.domain/ to point to the latest instances of files so there is no need to update your webserver to point to the new key material.

Advanced Configuration

Automatic renewal


Create a systemd certbot.service:

Description=Let's Encrypt renewal

ExecStart=/usr/bin/certbot renew --quiet --agree-tos

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 --deploy-hook "systemctl reload nginx.service" to the ExecStart command [1]. Of course use httpd.service instead of nginx.service if appropriate.

Note: Before adding a timer, check that the service is working correctly and is not trying to prompt anything.

Add a timer to check for certificate renewal twice a day and include a randomized delay so that everyone's requests for renewal will be spread over the day to lighten the Let's Encrypt server load [2]:

Description=Twice daily renewal of Let's Encrypt's certificates



Enable and start certbot.timer.

See also