Dev Notes

Software Development Resources by David Egan.

LetEncrypt Certbot on Ubuntu Xenial Xerus


LetsEncrypt, SSL
David Egan

LetsEncrypt is a free, open and automated certificate authority that operates for public benefit. It is a project of the non-profit Internet Security Research Group (ISRG).

This guide refers to installing and configuring LetsEncrypt and it’s client, Certbot, on Ubuntu 16.04 Xenial Xerus.

Certbot: the LetsEncrypt Client

Certbot is a client that allows you to fetch and configure SSL/TLS certificates. It also updates virtual host directives to ensure that site resources redirect to HTTPS.

Certbot is an easy-to-use automatic client that fetches and deploys SSL/TLS certificates for your webserver. Certbot was developed by EFF and others as a client for Let’s Encrypt and was previously known as “the official Let’s Encrypt client” or “the Let’s Encrypt Python client.” Certbot will also work with any other CAs that support the ACME protocol.

– https://certbot.eff.org/about/

Install Certbot

See up-to date instructions here.

sudo apt-get update
sudo apt-get install software-properties-common
sudo add-apt-repository ppa:certbot/certbot
sudo apt-get update
sudo apt-get install python-certbot-apache

Set Up Certs - Specific Domains

If you have pre-existing certs, this may be a good solution:

sudo certbot --apache -d example.com -d www.example.com

This command sets up certificates and creates appropriate virtual host directives that reference the certificates.

Set Up Certs - Interactive Session

You could run sudo certbot --apache instead - this will open an interactive session that will prompt you for various options. If upgrading from a previous version of the LetsEncrypt client, this is probably the best option:

sudo certbot --apache

# This outputs:
Saving debug log to /var/log/letsencrypt/letsencrypt.log
Starting new HTTPS connection (1): acme-v01.api.letsencrypt.org

Which names would you like to activate HTTPS for?
-------------------------------------------------------------------------------
1: example.com
2: www.example.com
-------------------------------------------------------------------------------
Select the appropriate numbers separated by commas and/or spaces, or leave input
blank to select all options shown (Enter 'c' to cancel):

The new vhost directives will be created in the /etc/apache2/sites-available directory in the format example.com-le-ssl.conf. The vhost configs will be automatically enabled, and a redirect will be written into the corresponding directive for port 80 (the non-HTTP original vhost directive).

Renew Certs

sudo certbot renew

Check Renew

Test that the renew process will work by performing a dry-run:

sudo certbot renew --dry-run

Automatic Renewal: Cronjob

Certificates have a three-month lifespan, so automatic renewal is recommended.

LetsEncrypt/Certbot sets up a cronjob. This is located at /etc/cron.d/certbot. It looks like this:

# /etc/cron.d/certbot: crontab entries for the certbot package
#
# Upstream recommends attempting renewal twice a day
#
# Eventually, this will be an opportunity to validate certificates
# haven't been revoked, etc.  Renewal will only occur if expiration
# is within 30 days.
SHELL=/bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin

0 */12 * * * root test -x /usr/bin/certbot -a \! -d /run/systemd/system && perl -e 'sleep int(rand(3600))' && certbot -q renew

The script first checks that /usr/bin/certbot exists and is executable, and that systemd is NOT present before running renew on a random minute of the hour.

The cronjob:

  • Runs every twelve hours
  • Tests that /usr/bin/certbot exists and is executable (i.e. certbot is installed)
  • ALSO (-a) tests that the directory /run/systemd/system does NOT exist (i.e. systemd is not present on the system)
  • If the previous two conditions are satisfied, pauses for a random number of seconds < 3600
  • When the sleep period has elapsed, certbot renew runs in quiet mode

Ubuntu 16.04? Your Cronjob Does Nothing!

The test command in the cronjob under /etc/cron.d/certbot stops execution if systemd is present - which in the case of Ubuntu, it is.

In this case, the timing of renewals is controlled in /lib/systemd/system/certbot.timer. Note that the execution of this is controlled in /etc/systemd/system/timers.target.wants, which contains a symlink to /lib/systemd/system/certbot.timer.

The /lib/systemd/system/certbot.timer file looks like this:

[Unit]
Description=Run certbot twice daily

[Timer]
OnCalendar=*-*-* 00,12:00:00
RandomizedDelaySec=3600
Persistent=true

[Install]
WantedBy=timers.target

This timer runs the service /lib/systemd/system/certbot.service, which looks like this:

[Unit]
Description=Certbot
Documentation=file:///usr/share/doc/python-certbot-doc/html/index.html
Documentation=https://letsencrypt.readthedocs.io/en/latest/
[Service]
Type=oneshot
ExecStart=/usr/bin/certbot -q renew
PrivateTmp=true

Note that by default, a service is activated with the same name (excluding suffix) as the timer - so certbot-timer activates certbot-service.

Support LetsEncrypt

You can support LetsEncrypt and Certbot by donating here.

References

comments powered by Disqus