Introduction

Let's Encrypt is a service offering free SSL certificates through an automated API. The most popular Let's Encrypt client is Certbot.

We won’t discuss the details of SSL configuration, but when you are done you will have a valid certificate that is automatically renewed. Additionally, you will be able to automate reloading your service to pick up the renewed certificate.

Certbot Commands

Certbot uses a number of different commands (also referred to as "subcommands") to request specific actions such as obtaining, renewing, or revoking certificates. The most important and commonly-used commands will be discussed throughout this document; an exhaustive list also appears near the end of the document.

The certbot script on your web server might be named letsencrypt if your system uses an older package, or certbot-auto if you used an alternate installation method. Throughout the docs, whenever you see certbot , swap in the correct name as needed.

Getting certificates (and choosing plugins)

The Certbot client supports two types of plugins for obtaining and installing certificates: authenticators and installers .

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. To obtain multiple separate certificates you will need to run Certbot multiple times.

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.

Plugins that do both can be used with the certbot run command, which is the default when no command is specified. The run subcommand can also be used to specify a combination of distinct authenticator and installer plugins.

Under the hood, plugins use one of several ACME protocol challenges to prove you control a domain. The options are http-01 (which uses port 80), tls-sni-01 (port 443) and dns-01 (requiring configuration of a DNS server on port 53, though that’s often not the same machine as your webserver). A few plugins support more than one challenge type, in which case you can choose one with --preferred-challenges .

There are also many third-party-plugins available. Below we describe in more detail the circumstances in which each plugin can be used, and how to use it.

Apache

The Apache plugin currently requires an OS with augeas version 1.0; currently it supports modern OSes based on Debian, Fedora, SUSE, Gentoo and Darwin. This automates both obtaining and installing certificates on an Apache webserver. To specify this plugin on the command line, simply include --apache .

Webroot

If you’re running a local webserver for which you have the ability to modify the content being served, and you’d prefer not to stop the webserver during the certificate issuance process, you can use the webroot plugin to obtain a certificate by including certonly and --webroot on the command line. In addition, you’ll need to specify --webroot-path or -w with the top-level directory (“web root”) containing the files served by your webserver. For example, --webroot-path /var/www/html or --webroot-path /usr/share/nginx/html are two common webroot paths.

If you’re getting a certificate for many domains at once, the plugin needs to know where each domain’s files are served from, which could potentially be a separate directory for each domain. When requesting a certificate for multiple domains, each domain will use the most recently specified --webroot-path . So, for instance,

~] certbot certonly --webroot -w /var/www/example/ -d www.example.com -d example.com -w /var/www/other -d other.example.net -d another.other.example.net

would obtain a single certificate for all of those names, using the /var/www/example webroot directory for the first two, and /var/www/other for the second two.

The webroot plugin works by creating a temporary file for each of your requested domains in ${webroot-path}/.well-known/acme-challenge . Then the Let’s Encrypt validation server makes HTTP requests to validate that the DNS for each requested domain resolves to the server running certbot. An example request made to your web server would look like:

66.133.109.36 - - [05/Jan/2016:20:11:24 -0500] "GET /.well-known/acme-challenge/HGr8U1IeTW4kY_Z6UIyaakzOkyQgPr_7ArlLgtZE8SX HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)"

Note that to use the webroot plugin, your server must be configured to serve files from hidden directories. If /.well-known is treated specially by your webserver configuration, you might need to modify the configuration to ensure that files inside /.well-known/acme-challenge are served by the webserver.

Nginx

The Nginx plugin has been distributed with Certbot since version 0.9.0 and should work for most configurations. We recommend backing up Nginx configurations before using it (though you can also revert changes to configurations with certbot --nginx rollback ). You can use it by providing the --nginx flag on the commandline.

$ certbot --nginx

Standalone

Use standalone mode to obtain a certificate if you don’t want to use (or don’t currently have) existing server software. The standalone plugin does not rely on any other server software running on the machine where you obtain the certificate.

To obtain a certificate using a “standalone” webserver, you can use the standalone plugin by including certonly and --standalone on the command line. This plugin needs to bind to port 80 or 443 in order to perform domain validation, so you may need to stop your existing webserver. To control which port the plugin uses, include one of the options shown below on the command line.

• --preferred-challenges http to use port 80
• --preferred-challenges tls-sni to use port 443

It must still be possible for your machine to accept inbound connections from the Internet on the specified port using each requested domain name.

Manual

If you’d like to obtain a certificate running certbot on a machine other than your target webserver or perform the steps for domain validation yourself, you can use the manual plugin. While hidden from the UI, you can use the plugin to obtain a certificate by specifying certonly and --manual on the command line. This requires you to copy and paste commands into another terminal session, which may be on a different computer.

The manual plugin can use either the http, dns or the tls-sni challenge. You can use the --preferred-challenges option to choose the challenge of your preference.

The http challenge will ask you to place a file with a specific name and specific content in the /.well-known/acme-challenge/ directory directly in the top-level directory ("web root") containing the files served by your webserver. In essence it’s the same as the webroot plugin, but not automated.

When using the dns challenge, certbot will ask you to place a TXT DNS record with specific contents under the domain name consisting of the hostname for which you want a certificate issued, prepended by _acme-challenge .

For example, for the domain example.com, a zone file entry would look like:

_acme-challenge.example.com. 300 IN TXT "gfj9Xq...Rg85nM"

When using the tls-sni challenge, certbot will prepare a self-signed SSL certificate for you with the challenge validation appropriately encoded into a subjectAlternatNames entry. You will need to configure your SSL server to present this challenge SSL certificate to the ACME server using SNI.

Additionally you can specify scripts to prepare for validation and perform the authentication procedure and/or clean up after it by using the --manual-auth-hook and --manual-cleanup-hook flags. This is described in more depth in the hooks section.

Combining plugins

Sometimes you may want to specify a combination of distinct authenticator and installer plugins. To do so, specify the authenticator plugin with --authenticator or -a and the installer plugin with --installer or -i .

For instance, you may want to create a certificate using the webroot plugin for authentication and the [apache}(https://certbot.eff.org/docs/using.html#apache) plugin for installation, perhaps because you use a proxy or CDN for SSL and only want to secure the connection between them and your origin server, which cannot use the tls-sni-01 challenge due to the intermediate proxy.

~] certbot run -a webroot -i apache -w /var/www/html -d example.com

Third-party plugins

There are also a number of third-party plugins for the client, provided by other developers. Many are beta/experimental, but some are already in widespread use:

If you’re interested, you can also write your own plugin .

Managing certificates

To view a list of the certificates Certbot knows about, run the certificates subcommand like:

~] certbot certificates

This returns information in the following format:

Found the following certs:
  Certificate Name: example.com
    Domains: example.com, www.example.com
    Expiry Date: 2017-02-19 19:53:00+00:00 (VALID: 30 days)
    Certificate Path: /etc/letsencrypt/live/example.com/fullchain.pem
    Private Key Path: /etc/letsencrypt/live/example.com/privkey.pem

Certificate Name shows the name of the certificate. Pass this name using the --cert-name flag to specify a particular certificate for the run, certonly, certificates, renew, and delete commands.

Example:

~] certbot certonly --cert-name example.com

Recreating and Updating Existing Certificates

You can use certonly or run subcommands to request the creation of a single new certificate even if you already have an existing certificate with some of the same domain names.

If a certificate is requested with run or certonly specifying a certificate name that already exists, Certbot updates the existing certificate. Otherwise a new certificate is created and assigned the specified name.

The --force-renewal , --duplicate , and --expand options control Certbot’s behavior when re-creating a certificate with the same name as an existing certificate. If you don’t specify a requested behavior, Certbot may ask you what you intended.

--force-renewal tells Certbot to request a new certificate with the same domains as an existing certificate. Each domain must be explicitly specified via -d . If successful, this certificate is saved alongside the earlier one and symbolic links (the live reference) will be updated to point to the new certificate. This is a valid method of renewing a specific individual certificate.

--duplicate tells Certbot to create a separate, unrelated certificate with the same domains as an existing certificate. This certificate is saved completely separately from the prior one. Most users will not need to issue this command in normal circumstances.

--expand tells Certbot to update an existing certificate with a new certificate that contains all of the old domains and one or more additional new domains. With the --expand option, use the -d option to specify all existing domains and one or more new domains.

Example:

~] certbot --expand -d existing.com,example.com,newdomain.com

If you prefer, you can specify the domains individually like this:

~] certbot --expand -d existing.com -d example.com -d newdomain.com

--allow-subset-of-names tells Certbot to continue with certificate generation if only some of the specified domain authorizations can be obtained. This may be useful if some domains specified in a certificate no longer point at this system.

Whenever you obtain a new certificate in any of these ways, the new certificate exists alongside any previously obtained certificates, whether or not the previous certificates have expired. The generation of a new certificate counts against several rate limits that are intended to prevent abuse of the ACME protocol, as described here .

Changing a Certificate’s Domains

The --cert-name flag can also be used to modify the domains a certificate contains, by specifying new domains using the -d or --domains flag. If certificate example.com previously contained example.com and www.example.com, it can be modified to only contain example.com by specifying only example.com with the -d or --domains flag. Example:

~] certbot certonly --cert-name example.com -d example.com

The same format can be used to expand the set of domains a certificate contains, or to replace that set entirely:

~] certbot certonly --cert-name example.com -d example.org,www.example.org

Let's Encrypt Rate Limits

source: https://letsencrypt.org/docs/rate-limits/

Let’s Encrypt provides rate limits to ensure fair usage by as many people as possible. We believe these rate limits are high enough to work for most people by default. We’ve also designed them so renewing a certificate almost never hits a rate limit, and so that large organizations can gradually increase the number of certificates they can issue without requiring intervention from Let’s Encrypt.

The main limit is Certificates per Registered Domain, (20 per week). A registered domain is, generally speaking, the part of the domain you purchased from your domain name registrar. For instance, in the name www.example.com, the registered domain is example.com. In new.blog.example.co.uk, the registered domain is example.co.uk. We use the Public Suffix List to calculate the registered domain.

If you have a lot of subdomains, you may want to combine them into a single certificate, up to a limit of 100 Names per Certificate. Combined with the above limit, that means you can issue certificates containing up to 2,000 unique subdomains per week. A certificate with multiple names is often called a SAN certificate, or sometimes a UCC certificate.

We also have a Duplicate Certificate limit of 5 certificates per week. A certificate is considered a duplicate of an earlier certificate if they contain the exact same set of hostnames, ignoring capitalization and ordering of hostnames. For instance, if you requested a certificate for the names [www.example.com, example.com], you could request four more certificates for [www.example.com, example.com] during the week. If you changed the set of names by adding [blog.example.com], you would be able to request additional certificates.

Sources

https://certbot.eff.org/docs/intro.html