About
Certbot is an acme client (Let’s Encrypt CA) (or any other CA) to issue SSL certificates.
Certbot is an easy-to-use client that fetches a certificate from Let’s Encrypt—an open certificate authority launched by the EFF, Mozilla, and others—and deploys it to a web server.
Before May 2016, Certbot was knwon as:
- letsencrypt
- or letsencrypt-auto
Let’s Encrypt started in November 2014 as an initiative created by the Internet Security Research Group (ISRG). The was to create a certificate authority that provides free SSL certificates using an automated process.
Usage
- Certbot runs on Unix-based operating systems
- you’ll need root or administrator access to your web server to run Certbot.
- Certbot is meant to be run directly on your web server
- Only for admin: Certbot allows its user to specify arbitrary file locations and run arbitrary scripts.
Plugin
A plugin can be:
- an authenticator
- or/and an installer
Plugins that do both can be used with the certbot run command, which is the default when no command is specified.
See list of plugin an their challenge at Getting certificates (and choosing plugins)
Authenticator
Authenticators are plugins used with the certonly command to obtain a certificate. The authenticator validates that you control the domain(s) you are requesting a certificate for, obtains a certificate for the specified domain(s), and places the certificate in the /etc/letsencrypt directory on your machine. The authenticator does not install the certificate (it does not edit any of your server’s configuration files to serve the obtained certificate). If you specify multiple domains to authenticate, they will all be listed in a single certificate.
Installers
Installers are Plugins used with the install command to install a certificate. These plugins can modify your webserver’s configuration to serve your website over HTTPS using certificates obtained by certbot.
Files
Let’s Encrypt CA issues short-lived certificates (90 days). Make sure you renew the certificates at least once in 3 months.
All generated keys and issued certificates can be found in /etc/letsencrypt/live/domain where domain is the first domain passed in via -d parameter
/etc/letsencrypt/archive and /etc/letsencrypt/keys contain all previous keys and certificates, while /etc/letsencrypt/live symlinks to the latest versions.
All files are PEM-encoded
The following files are available:
- privkey.pem Private key for the certificate that the server will read to enable TLS/SSL
- Apache: SSLCertificateKeyFile,
- Nginx: ssl_certificate_key.
- fullchain.pem - All certificates, including server certificate (aka leaf certificate or end-entity certificate). The server certificate is the first one in this file, followed by any intermediates.
- Apache >= 2.4.8: SSLCertificateFile,
- Nginx: ssl_certificate.
- cert.pem and chain.pem (less common - needs to provide both)
- cert.pem contains the server certificate by itself,
- chain.pem contains the additional intermediate certificate in the chain to validate the certificate
- Apache < 2.4.8 needs these for SSLCertificateFile. and SSLCertificateChainFile, respectively.
- Nginx: chain.pem should be provided as the ssl_trusted_certificate to validate OCSP responses. If you’re using OCSP stapling with Nginx >= 1.3.7,
Verification
You can verify the certificate with the following command:
cd /etc/letsencrypt/live/$domain
# then
openssl verify -untrusted chain.pem -verbose fullchain.pem
#or
openssl verify -untrusted chain.pem -verbose cert.pem
# or without untrusted by building the full chain
wget https://letsencrypt.org/certs/trustid-x3-root.pem.txt
cat chain.pem trustid-x3-root.pem.txt > completechain.pem
openssl verify -CAfile completechain.pem -verbose fullchain.pem
where:
- untrusted was added because the intermediate letsencrypt certificate is not in the ca certificate but its root well.
Output:
fullchain.pem: OK
# or
cert.pem: OK
Command
Usage
certbot --help
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
certbot [SUBCOMMAND] [options] [-d DOMAIN] [-d DOMAIN] ...
Certbot can obtain and install HTTPS/TLS/SSL certificates. By default,
it will attempt to use a webserver both for obtaining and installing the
certificate. The most common SUBCOMMANDS and flags are:
obtain, install, and renew certificates:
(default) run Obtain & install a certificate in your current webserver
certonly Obtain or renew a certificate, but do not install it
renew Renew all previously obtained certificates that are near
expiry
enhance Add security enhancements to your existing configuration
-d DOMAINS Comma-separated list of domains to obtain a certificate for
(the certbot apache plugin is not installed)
--standalone Run a standalone webserver for authentication
--nginx Use the Nginx plugin for authentication & installation
--webroot Place files in a server's webroot folder for authentication
--manual Obtain certificates interactively, or using shell script
hooks
-n Run non-interactively
--test-cert Obtain a test certificate from a staging server
--dry-run Test "renew" or "certonly" without saving any certificates
to disk
manage certificates:
certificates Display information about certificates you have from Certbot
revoke Revoke a certificate (supply --cert-path or --cert-name)
delete Delete a certificate
manage your account:
register Create an ACME account
unregister Deactivate an ACME account
update_account Update an ACME account
--agree-tos Agree to the ACME server's Subscriber Agreement
-m EMAIL Email address for important account notifications
More detailed help:
-h, --help [TOPIC] print this message, or detailed help on a topic;
the available TOPICS are:
all, automation, commands, paths, security, testing, or any of the
subcommands or plugins (certonly, renew, install, register, nginx,
apache, standalone, webroot, etc.)
-h all print a detailed help page including all topics
--version print the version number
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Nginx
certbot --help nginx
usage:
certbot [SUBCOMMAND] [options] [-d DOMAIN] [-d DOMAIN] ...
Certbot can obtain and install HTTPS/TLS/SSL certificates. By default,
it will attempt to use a webserver both for obtaining and installing the
certificate.
optional arguments:
-h, --help show this help message and exit
-c CONFIG_FILE, --config CONFIG_FILE
path to config file (default: /etc/letsencrypt/cli.ini
and ~/.config/letsencrypt/cli.ini)
--https-port HTTPS_PORT
Port used to serve HTTPS. This affects which port
Nginx will listen on after a LE certificate is
installed. (default: 443)
nginx:
Nginx Web Server plugin
--nginx-server-root NGINX_SERVER_ROOT
Nginx server root directory. (default: /etc/nginx)
--nginx-ctl NGINX_CTL
Path to the 'nginx' binary, used for 'configtest' and
retrieving nginx version number. (default: nginx)
Renew
To non-interactively renew *all* of your certificates, run
certbot renew
Installation
- Enable EPEL repo
Glossary
expand
expand means that you will add a domain to a certificate.
Support
0001 directory
When playing with certbot, you may see the certificate in 0001 directory.
Resolution:
cd /etc/letsencrypt
rm -rf live
rm -rf renewal
rm -rf archive
and rerun your code