Let’s Encrypt
How It Works
Anyone who has gone through the trouble of setting up a secure website knows what a hassle getting and maintaining a certificate can be. Let’s Encrypt automates away the pain and lets site operators turn on and manage HTTPS with simple commands.
No validation emails, no complicated configuration editing, no expired certificates breaking your website. And of course, because Let’s Encrypt provides certificates for free, no need to arrange payment.
This page describes how to carry out the most common certificate management functions using the Let’s Encrypt client. You’re welcome to use any compatible client, but we only provide instructions for using the client that we provide.
If you’d like to know more about how this works behind the scenes, check out our technical overview.
Installing Let’s Encrypt
Note: Let’s Encrypt is in beta. Please don’t use it unless you’re comfortable with beta software that may contain bugs.
If your operating system includes a packaged copy of letsencrypt, install it from there and use the letsencrypt command. Otherwise, you can use our letsencrypt-auto wrapper script to get a copy quickly:
$ git clone https://github.com/letsencrypt/letsencrypt
$ cd letsencrypt
$ ./letsencrypt-auto --help
letsencrypt-auto accepts the same flags as letsencrypt; it installs all of its own dependencies and updates the client code automatically (but it’s comparatively slow and large in order to achieve that).
How To Use The Client
The Let’s Encrypt client supports a number of different “plugins” that can be used to obtain and/or install certificates. A few examples of the options are included below:
If you’re running Apache on a recent Debian-based OS, you can try the Apache plugin, which automates both obtaining and installing certs:
./letsencrypt-auto --apache
On other platforms automatic installation is not yet available, so you will have to use the certonly command. Here are some examples:
To obtain a cert using a “standalone” webserver (you may need to temporarily stop your exising webserver) for example.com and www.example.com:
./letsencrypt-auto certonly --standalone -d example.com -d www.example.com
To obtain a cert using the “webroot” plugin, which can work with the webroot directory of any webserver software:
./letsencrypt-auto certonly --webroot -w /var/www/example -d example.com -d www.example.com -w /var/www/thing -d thing.is -d m.thing.is
The this will obtain a single cert for example.com, www.example.com, thing.is, and m.thing.is; it will place files below /var/www/example to prove control of the first two domains, and under /var/www/thing for the second pair.
Renewing a Certificate
To renew a certificate, simply run letsencrypt again providing the same values when prompted. In almost all circumstances, renewal should be performed with the certonly subcommand (reloading your webserver config should be enough to deploy the renewed cert). Flags exist to make this noninteractive, for instance:
./letsencrypt-auto certonly --keep-until-expiring --webroot -w /var/www/example.com -d example.com,www.example.com -w /var/www/thing -d thing.is,m.thing.is
Writing your own renewal script
We will be providing scripts to automate this renewal in the next few weeks, but if you wish to roll your own renewal script in the mean time, you can put a certonly invokation of the client in a script followed by a reload command for your webserver. For instance, apache users might want a script like this:
#!/bin/sh
if ! /path/to/letsencrypt-auto certonly -tvv --apache --keep -d example.com,www.example.com,thing.is > /var/log/letsencrypt/renew.log 2>&1 ; then
echo Automated renewal failed:
cat /var/log/letsencrypt/renew.log
exit 1
fi
apachectl graceful
While users of the standalone plugin might want a script like this:
#!/bin/sh
service nginx stop # or whatever your webserver is
if ! /path/to/letsencrypt-auto certonly -tvv --standalone --keep -d example.com,www.example.com,thing.is > /var/log/letsencrypt/renew.log 2>&1 ; then
echo Automated renewal failed:
cat /var/log/letsencrypt/renew.log
exit 1
fi
service nginx start # or whatever your webserver is
You can test your script by replacing --keep-until-expiring with --renew-by-default; that will force a renewal even if your cert isn’t close to expiry. If you have an OS packaged version of the client, call letsencrypt rather than/path/to/letsencrypt-auto. Note that scripts which call letsencrypt-auto will auto-update the letsencrypt client, for better and worse. If you don’t want that, but obtained the client with letsencrypt-auto, you can call the client directly insidethe virtual environment it created: /home/user/.local/share/letsencrypt/bin/letsencrypt rather than/path/to/letsencrypt-auto.
Once you’re happy with your script, you can run it with cron or systemd. We recommend running renewal scripts at least daily, at a random hour and minute. This gives the script many days to retry renewal in case of transient network failures or server outages.
Let’s Encrypt is working hard to further automate renewal. Forthcoming releases will include flags to force non-interactive/quiet operation, a default script to be run from crontab or systemd; a mechanism to remember the choice of plugins that you made when obtaining a cert, and customisable schedules for renewal and deployment of renewed certs.
Revoking a Certificate
The following command can be used to revoke a particular certificate.
$ letsencrypt revoke --cert-path example-cert.pem
Full Documentation
For more information on the official client, please see the full documentation.