Difference between revisions of "Certbot"

From ArchWiki
Jump to navigation Jump to search
(→‎Installation: Since version 0.16, certbot-apache works out-of-box on on Arch Linux)
(Undo revision 577285 by Southerntofu (talk) - the file is provided by ca-certificates-utils which is an indirect dependency of certbot)
Tag: Undo
 
(131 intermediate revisions by 34 users not shown)
Line 1: Line 1:
 
[[Category:Networking]]
 
[[Category:Networking]]
 
[[Category:Encryption]]
 
[[Category:Encryption]]
[[ja:Let’s Encrypt]]
+
[[Category:Commands]]
[https://letsencrypt.org/ Let’s Encrypt] is a free, automated, and open certificate authority utilizing the [[Wikipedia:Automated Certificate Management Environment|ACME]] protocol.
+
[[Category:Electronic Frontier Foundation]]
 
+
[[ja:Certbot]]
The official client is called '''Certbot''', which allows to request valid X.509 certificates straight from the command line.
+
[[ru:Certbot]]
A minimal client with manual CSR creation is available at {{AUR|acme-tiny}}, clients suitable for scripts are {{AUR|simp_le-git}} and {{AUR|letsencrypt-cli}}.
+
[https://github.com/certbot/certbot Certbot] is [https://www.eff.org/ 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 [https://letsencrypt.org/ Let's Encrypt].
  
 
== Installation ==
 
== Installation ==
Line 12: Line 12:
  
 
Plugins are available for automated configuration and installation of the issued certificates in web servers:
 
Plugins are available for automated configuration and installation of the issued certificates in web servers:
* The experimental plugin for [[Nginx]] is provided with the {{Pkg|certbot-nginx}} package.
+
 
* Automated installation using the [[Apache HTTP Server]] is enabled via the {{Pkg|certbot-apache}} package.
+
* The [[Nginx]] plugin can be installed with the {{Pkg|certbot-nginx}} package.
 +
* The [[Apache HTTP Server]] plugin can be installed with the {{Pkg|certbot-apache}} package.
  
 
== Configuration ==
 
== Configuration ==
  
Consult the [https://certbot.eff.org/docs/ Certbot documentation] for more information about creation and usage of certificates.
+
Consult the [https://certbot.eff.org/docs/ Certbot documentation] for more information about creation and usage of certificates.  
 +
 
 +
=== Plugins ===
 +
 
 +
{{Warning|Configuration files may be rewritten to add settings and paths for Certbot certificates when using a plugin. Creating a '''backup''' first is recommended.}}
 +
 
 +
==== Nginx ====
 +
 
 +
The plugin {{pkg|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 [[nginx#Server blocks|server-blocks]]:
 +
 
 +
# certbot --nginx
 +
 
 +
To renew certificates:
 +
 
 +
# certbot renew
 +
 
 +
To change certificates without modifying nginx config files:
 +
 
 +
# certbot --nginx certonly
 +
 
 +
See [https://certbot.eff.org/#arch-nginx Certbot-Nginx on Arch Linux] for more information and [[#Automatic renewal]] to keep installed certificates valid.
 +
 
 +
===== Managing Nginx server blocks =====
  
=== Webroot ===
+
The following example may be used in all [[nginx#Server blocks|server blocks]] when managing these files manually:
{{Note|
 
* The Webroot method requires '''HTTP on port 80''' for Certbot to validate.
 
** For Certbot to validate using '''HTTPS on port 443''', the Nginx ('''--nginx''') or Apache ('''--apache''') plugin must be used instead of the Webroot ('''--webroot''') method.
 
* 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 {{ic|http://domain.tld/.well-known}}.
 
  
 +
{{hc|/etc/nginx/sites-available/example|2=
 +
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;
 +
  ..
 +
}
 
}}
 
}}
  
When using the webroot method the Certbot client places a challenge response inside {{ic|/path/to/domain.tld/html/.well-known/acme-challenge/}} which is used for validation.
+
See [[nginx#TLS]] for more information.
 +
 
 +
It's also possible to create a separated config file and include it in each server block:
  
The use of this method is recommend over a manual install; it offers automatically renewal and easier certificate management.
+
{{hc|/etc/nginx/conf/001-certbot.conf|2=
 +
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;
 +
}}
  
{{Tip|1=The following initial [[Nginx#Server_blocks|nginx server]] configuration may be helpful to obtain a first-time certificate:
+
{{hc|/etc/nginx/sites-available/example|<nowiki>
{{hc|/etc/nginx/servers-available/domain.tld|
 
<nowiki>
 
 
server {
 
server {
   listen 80;
+
   listen 443 ssl http2;
   listen [::]:80;
+
   listen [::]:443 ssl http2; # Listen on IPv6
   server_name domain.tld;
+
   include conf/001-certbot.conf;
   root /usr/share/nginx/html;
+
   ..
  location / {
 
    index index.htm index.html;
 
  }
 
 
}
 
}
 +
</nowiki>}}
 +
 +
==== Apache ====
 +
 +
The plugin {{pkg|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.
  
# ACME challenge
+
First time setup of [[Apache_HTTP_Server#Virtual_hosts|virtual hosts]]:
location ^~ /.well-known {
 
  allow all;
 
  alias /var/lib/letsencrypt/.well-known/;
 
  default_type "text/plain";
 
  try_files $uri =404;
 
}
 
</nowiki>
 
}}
 
}}
 
  
==== Obtain certificate(s)  ====
+
  # certbot --apache
Request a certificate for {{ic|domain.tld}} using {{ic|/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'''
 
  
To add a (sub)domain, include all registered domains used on the current setup:
+
To renew certificates:
# certbot certonly --email '''email@example.com''' --webroot -w '''/path/to/sub.domain.tld/html/''' -d '''domain.tld,sub.domain.tld'''
 
  
To renew (all) the current certificate(s):
 
 
  # certbot renew
 
  # certbot renew
  
See [[#Automatic renewal]] as alternative approach.
+
To change certificates without modifying apache config files:
 +
 
 +
# certbot --apache certonly
 +
 
 +
See [https://certbot.eff.org/#arch-apache Certbot-Apache on Arch Linux] for more information and [[#Automatic renewal]] to keep installed certificates valid.
  
=== Manual ===
+
===== Managing Apache virtual hosts =====
  
{{Note|
+
The following example may be used in all [[Apache HTTP Server#Virtual hosts|virtual hosts]] when managing these files manually:
* The running webserver has to temporarily stopped.
 
* Automatically renewal is not available when performing manual install, see [[#Webroot]] instead.
 
}}
 
  
If there is no plugin for your web server, use the following command:
+
{{hc|/etc/httpd/conf/extra/001-certbot.conf|2=
# certbot certonly --manual
+
<IfModule mod_ssl.c>
 +
<VirtualHost *:443>
  
When preferring to use DNS challenge (TXT record) use:
+
Include /etc/letsencrypt/options-ssl-apache.conf
# certbot certonly --manual --preferred-challenges dns
+
SSLCertificateFile /etc/letsencrypt/live/'domain'/fullchain.pem
 +
SSLCertificateKeyFile /etc/letsencrypt/live/'domain'/privkey.pem
  
This will automatically verify your domain and create a private key and certificate pair. These are placed in {{ic|/etc/letsencrypt/live/''your.domain''/}}.
+
</VirtualHost>
 +
</IfModule>
 +
}}
  
You can then manually configure your web server to use the key and certificate in that directory.
+
{{hc|/etc/httpd/conf/httpd.conf|<nowiki>
 +
  <IfModule mod_ssl.c>
 +
  Listen 443
 +
  </IfModule>
  
{{Note|Running this command multiple times will create multiple sets of files with a trailing number in {{ic|/etc/letsencrypt/live/''your.domain''/}} so take care to rename them in that directory or in the webserver config file.}}
+
  Include conf/extra/001-certbot.conf
 +
  ..
 +
</nowiki>}}
  
== Advanced Configuration ==
+
See [[Apache HTTP Server#TLS]] for more information.
  
=== Webserver Configuration ===
+
=== Webroot ===
Instead of using plugins for automatic configuration, it may be preferred to enable SSL for a server manually.
 
  
{{Tip|
+
{{Note|
* Mozilla has a useful [https://wiki.mozilla.org/Security/Server_Side_TLS SSL/TLS article] which includes an [https://mozilla.github.io/server-side-tls/ssl-config-generator/ automated tool] to help create a more secure configuration.
+
* The Webroot method requires '''HTTP on port 80''' for Certbot to validate.
* [https://cipherli.st Cipherli.st] provides strong SSL implementation examples and tutorial for most modern webservers.
+
* The Server Name must match that of its corresponding DNS.
 +
* Permissions may need to be altered on the host to allow read-access to {{ic|http://domain.tld/.well-known}}.
 
}}
 
}}
  
==== nginx ====
+
When using the webroot method the Certbot client places a challenge response inside {{ic|/path/to/domain.tld/html/.well-known/acme-challenge/}} which is used for validation.
An example of the server {{ic|domain.tld}} using the signed SSL-certificate of Let's Encrypt:
 
{{hc|/etc/nginx/servers-available/domain.tld|
 
<nowiki>
 
# redirect to https
 
server {
 
  listen 80;
 
  listen [::]:80;
 
  server_name domain.tld;
 
  return 301 https://$host$request_uri;
 
}
 
  
server {
+
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.
  listen 443 ssl http2;
 
  listen [::]:443 ssl http2;
 
  ssl_certificate /etc/letsencrypt/live/domain.tld/fullchain.pem;
 
  ssl_certificate_key /etc/letsencrypt/live/domain.tld/privkey.pem;
 
  ssl_trusted_certificate /etc/letsencrypt/live/domain.tld/chain.pem;
 
  ssl_session_timeout 1d;
 
  ssl_session_cache shared:SSL:50m;
 
  ssl_session_tickets off;
 
  ssl_prefer_server_ciphers on;
 
  add_header Strict-Transport-Security max-age=15768000;
 
  ssl_stapling on;
 
  ssl_stapling_verify on;
 
  server_name domain.tld;
 
  ..
 
}
 
  
# A subdomain uses the same SSL-certifcate:
+
==== Mapping ACME-challenge requests ====
server {
 
  listen 443 ssl http2;
 
  listen [::]:443 ssl http2;
 
  ssl_certificate /etc/letsencrypt/live/domain.tld/fullchain.pem;
 
  ssl_certificate_key /etc/letsencrypt/live/domain.tld/privkey.pem;
 
  ssl_trusted_certificate /etc/letsencrypt/live/domain.tld/chain.pem;
 
  ..
 
  server_name sub.domain.tld;
 
  ..
 
}
 
  
# ACME challenge
+
{{Accuracy|In the ''webroot'' way, the {{ic|/var/lib/letsencrypt}} path is dictated by ''certbot''. Manual creation is not necessary, that applies to [[#Manual]].}}
location ^~ /.well-known {
 
  allow all;
 
  alias /var/lib/letsencrypt/.well-known/;
 
  default_type "text/plain";
 
  try_files $uri =404;
 
}
 
</nowiki>
 
}}
 
  
=== Multiple domains ===
+
Management of can be made easier by mapping all HTTP-requests for {{ic|.well-known/acme-challenge}} to a single folder, e.g. {{ic|/var/lib/letsencrypt}}.
Management of can be made easier by mapping all HTTP-requests for {{ic|/.well-known/acme-challenge/}} to a single folder, e.g. {{ic|/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''):
+
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
 
  # mkdir -p /var/lib/letsencrypt/.well-known
 
  # chgrp http /var/lib/letsencrypt
 
  # chgrp http /var/lib/letsencrypt
 
  # chmod g+s /var/lib/letsencrypt
 
  # chmod g+s /var/lib/letsencrypt
  
==== nginx ====
+
===== nginx =====
  
 
Create a file containing the location block and include this inside a server block:
 
Create a file containing the location block and include this inside a server block:
{{hc|/etc/nginx/conf.d/letsencrypt.conf|
+
{{hc|/etc/nginx/conf.d/letsencrypt.conf|<nowiki>
<nowiki>
+
location ^~ /.well-known/acme-challenge/ {
location ^~ /.well-known {
 
 
   allow all;
 
   allow all;
   alias /var/lib/letsencrypt/.well-known/;
+
   root /var/lib/letsencrypt/;
 
   default_type "text/plain";
 
   default_type "text/plain";
 
   try_files $uri =404;
 
   try_files $uri =404;
Line 178: Line 165:
 
</nowiki>}}
 
</nowiki>}}
  
==== Apache ====
+
===== Apache =====
  
 
Create the file {{ic|/etc/httpd/conf/extra/httpd-acme.conf}}:
 
Create the file {{ic|/etc/httpd/conf/extra/httpd-acme.conf}}:
Line 189: Line 176:
 
</Directory>
 
</Directory>
 
</nowiki>}}
 
</nowiki>}}
 +
 
Including this in {{ic|/etc/httpd/conf/httpd.conf}}:
 
Including this in {{ic|/etc/httpd/conf/httpd.conf}}:
 
{{hc|/etc/httpd/conf/httpd.conf|<nowiki>
 
{{hc|/etc/httpd/conf/httpd.conf|<nowiki>
 
Include conf/extra/httpd-acme.conf
 
Include conf/extra/httpd-acme.conf
 
</nowiki>}}
 
</nowiki>}}
 +
 +
==== Obtain certificate(s)  ====
 +
 +
{{Expansion|detail lacking to successfully accomplish task being taught|section=accuracy_flag}}
 +
Request a certificate for {{ic|domain.tld}} using {{ic|/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 {{ic|/etc/letsencrypt/archive/''your.domain''/}} and symlinked from {{ic|/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 {{ic|/etc/letsencrypt/archive/''your.domain''/}}.  Certbot automatically updates the symlinks in {{ic|/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 ===
 
=== Automatic renewal ===
Line 204: Line 222:
 
[Service]
 
[Service]
 
Type=oneshot
 
Type=oneshot
ExecStart=/usr/bin/certbot renew --quiet --agree-tos}}
+
ExecStart=/usr/bin/certbot renew --quiet --agree-tos
 
+
}}
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 {{ic|certbot.service}} file:
 
  
* Apache: {{ic|1=ExecStartPost=/bin/systemctl reload httpd.service}}
+
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 {{ic|--deploy-hook "systemctl reload nginx.service"}} to the {{ic|ExecStart}} command [https://certbot.eff.org/docs/using.html#renewing-certificates]. Of course use {{ic|httpd.service}} instead of {{ic|nginx.service}} if appropriate.
* nginx: {{ic|1=ExecStartPost=/bin/systemctl reload nginx.service}}
 
  
{{Note|Before adding a [[systemd/Timers|timer]], check that the service is working correctly and is not trying to prompt anything.}}
+
{{Note|Before adding a [[systemd/Timers|timer]], check that the service is working correctly and is not trying to prompt anything. Note that the service may take up to 480 seconds to complete since a delay is added to calling certbot interactively since [https://github.com/certbot/certbot/blob/master/CHANGELOG.md#0290---2018-12-05 v0.29.0].}}
  
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 evenly spread over the day to lighten the Let's Encrypt server load [https://certbot.eff.org/#arch-nginx]:
+
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 [https://certbot.eff.org/#arch-nginx]:
  
 
{{hc|1=/etc/systemd/system/certbot.timer|
 
{{hc|1=/etc/systemd/system/certbot.timer|
Line 229: Line 245:
 
[[Enable]] and [[start]] {{ic|certbot.timer}}.
 
[[Enable]] and [[start]] {{ic|certbot.timer}}.
  
===== Alternative services =====
+
=== Automatic renewal for wildcard certificates ===
When using the standalone method you should stop your webserver before executing the renew request, and start your webserver when Certbot is finished. Certbot provides hooks to automatically stop and restart a web server.
+
 
 +
The process is fairly simple. To issue a wildcard certificate, you have to do it via a DNS challenge request, [https://community.letsencrypt.org/t/acme-v2-and-wildcard-certificate-support-is-live/55579 using the ACMEv2 protocol].
 +
 
 +
While issuing a certificate manually is easy, it's 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 [https://tools.ietf.org/html/rfc2136 rfc2136] for which certbot has a plugin packaged in {{Pkg|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'''
  
====== nginx ======
+
and add it in the configuration file:
{{hc|1=/etc/systemd/system/certbot.service|
+
 
2=[Unit]
+
{{hc|1=/etc/named.conf|
Description=Let's Encrypt renewal
+
2=...
 +
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'''";
 +
};
 +
...}}
 +
 
 +
[[Restart]] {{ic|named.service}}.
 +
 
 +
==== Configure certbot for rfc2136 ====
 +
 
 +
Create a configuration file for the rfc2136 plugin.
 +
 
 +
{{hc|1=/etc/letsencrypt/rfc2136.ini|
 +
2=dns_rfc2136_server = '''IP.ADD.RE.SS'''
 +
dns_rfc2136_name = '''example-key'''
 +
dns_rfc2136_secret = '''INSERT_KEY_WITHOUT_QUOTES'''
 +
dns_rfc2136_algorithm = HMAC-SHA512}}
  
[Service]
+
Since the file contains a copy of the secret key, secure it with [[chmod]] by removing the group and others permissions.
Type=oneshot
 
ExecStart=/usr/bin/certbot renew --post-hook "/usr/bin/systemctl restart nginx.service" --agree-tos}}
 
  
====== Apache ======
+
Test what we did:
{{hc|1=/etc/systemd/system/certbot.service|
+
# 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''''
2=[Unit]
 
Description=Let's Encrypt renewal
 
  
[Service]
+
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 {{ic|certbot renew}} from now on, see [[#Automatic renewal]].
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}}
 
  
 
== See also ==
 
== See also ==
  
 +
* [[Transport Layer Security#ACME clients]]
 +
* [[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]

Latest revision as of 17:15, 11 July 2019

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:

Configuration

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

Plugins

Warning: Configuration files may be rewritten to add settings and paths for Certbot certificates when using a plugin. Creating a backup first is recommended.

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 config 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:

/etc/nginx/sites-available/example
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;
  ..
}

See nginx#TLS for more information.

It's also possible to create a separated config file and include it in each server block:

/etc/nginx/conf/001-certbot.conf
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
server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2; # Listen on IPv6
  include conf/001-certbot.conf;
  ..
}

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 config 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:

/etc/httpd/conf/extra/001-certbot.conf
<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/httpd.conf
  <IfModule mod_ssl.c>
  Listen 443
  </IfModule>

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

See Apache HTTP Server#TLS for more information.

Webroot

Note:
  • The Webroot method requires HTTP on port 80 for Certbot to validate.
  • The Server Name must match that of its 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
nginx

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

/etc/nginx/conf.d/letsencrypt.conf
location ^~ /.well-known/acme-challenge/ {
  allow all;
  root /var/lib/letsencrypt/;
  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.d/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

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.

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.

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

systemd

Create a systemd certbot.service:

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

[Service]
Type=oneshot
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. Note that the service may take up to 480 seconds to complete since a delay is added to calling certbot interactively since v0.29.0.

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]:

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

[Timer]
OnCalendar=0/12:00:00
RandomizedDelaySec=1h
Persistent=true

[Install]
WantedBy=timers.target

Enable and start certbot.timer.

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's 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 rfc2136 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:

/etc/named.conf
...
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";
};
...

Restart named.service.

Configure certbot for rfc2136

Create a configuration file for the rfc2136 plugin.

/etc/letsencrypt/rfc2136.ini
dns_rfc2136_server = IP.ADD.RE.SS
dns_rfc2136_name = example-key
dns_rfc2136_secret = INSERT_KEY_WITHOUT_QUOTES
dns_rfc2136_algorithm = HMAC-SHA512

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