Skip to content

Requesting Host Certificates Using Let's Encrypt

Let's Encrypt is a free, automated, and open CA frequently used for web services; see the security team's position on Let's Encrypt for more details. Let's Encrypt can be used to obtain host certificates as an alternative to InCommon if your institution does not have an InCommon subscription.

Let's Encrypt uses an automated script named certbot for requesting and renewing host certs. certbot binds to port 80 when running, so services running on port 80 (such as HTCondor-CE View service) must be temporarily stopped before running certbot. In addition, port 80 must be open to the world while certbot is running. If this does not work for your host, see the alternate renewal methods section below. Let's Encrypt host certs expire every three months so it is important to set up automated renewal.

Installation and Obtaining the Initial Certificate

  1. Install the certbot package (available from the EPEL repository):

    root@host # yum install certbot

  2. Stop services running on port 80 if there are any.

  3. Run the following command to obtain the host certificate with Let's Encrypt:

    root@host # certbot certonly --standalone --email <ADMIN_EMAIL> -d <HOST>

  4. Set up hostcert/hostkey links:

    If using host certificates for Pelican/OSDF:
:::console
root@host # ln -sf /etc/letsencrypt/live/*/fullchain.pem /etc/pki/tls/certs/pelican.crt
root@host # ln -sf /etc/letsencrypt/live/*/privkey.pem /etc/pki/tls/private/pelican.key
root@host # chmod 0600 /etc/letsencrypt/archive/*/privkey*.pem

If using host certificates for other software:
:::console
root@host # ln -sf /etc/letsencrypt/live/*/cert.pem /etc/grid-security/hostcert.pem
root@host # ln -sf /etc/letsencrypt/live/*/privkey.pem /etc/grid-security/hostkey.pem
root@host # chmod 0600 /etc/letsencrypt/archive/*/privkey*.pem

    Note that Pelican requires the full certificate chain, not just the certificate, so the pelican.crt symlink needs to point to fullchain.pem, not cert.pem.

  5. Restart services running on port 80 if there were any.

Renewing Let's Encrypt host certificates

You can manually renew your certificate with the following command:

root@host # certbot renew

The certificate will be renewed if it is close to expiring.

Disable services listening on port 80

Just like with obtaining a new certificate, renewing a certificate requires you to temporarily disable services running on port 80 so that certbot can verify the host.

Automating renewals using systemd timers

To automate renewal using systemd, you'll need to create two files: The first is a service file that tells systemd how to invoke certbot. The second is to generate a timer file that tells systemd how often to run the service. The steps to setup the timer are as follows:

  1. Create a service file called /etc/systemd/system/certbot.service with the following contents

    [Unit]
Description=Let's Encrypt renewal

[Service]
Type=oneshot
ExecStart=/usr/bin/certbot renew --quiet --agree-tos

  2. Once the certbot service is working correctly, you will need to create the timer file. Create the timer file at /etc/systemd/system/certbot.timer) with the following contents:

    [Unit]
Description=Let's Encrypt renewal timer

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

[Install]
WantedBy=timers.target

  3. Update the systemd manager configuration:

    root@host # systemctl daemon-reload

  4. Start and enable the certbot timer:

    root@host # systemctl enable --now certbot.timer

You can verify that the timer is active by running systemctl list-timers.

Note

Verify that the service has started correctly by running systemctl status certbot.service. The timer may fail without warnings if the service does not run correctly.

Pre- and post-renewal hooks

certbot provides the ability to run scripts before and/or after certificate renewal via command hooks. Common uses for these hooks include:

  • Copying the renewed certificate so that it can be used for a separate service (such as XRootD)
  • Shutting down and restarting a service running on port 80
  • Temporarily opening up the firewall

To do this, call certbot with --pre-hook <COMMAND> for a command or script to run before renewal, and --post-hook <COMMAND> for a command or script to run after renewal. The command(s) will only be run if the certificate is actually renewed.

Example

This example is for a host running CEView and XRootD standalone; CEView needs to be stopped so it doesn't block port 80, and XRootD needs its certificate in a separate location.

Create the following scripts:

/root/bin/certbot-pre.sh 

#!/bin/bash
condor_ce_off -daemon CEVIEW

/root/bin/certbot-post.sh 

#!/bin/bash
cd /etc/grid-security
cp -f hostcert.pem xrd/xrdcert.pem
cp -f hostkey.pem xrd/xrdkey.pem
chown -R xrootd:xrootd xrd
condor_ce_on -daemon CEVIEW
systemctl restart xrootd@standalone

Then call certbot as follows:

root@host # certbot renew --pre-hook /root/bin/certbot-pre.sh \
                          --post-hook /root/bin/certbot-post.sh

For automated renewal, edit the certbot.service file that you created above and add the --pre-hook <COMMAND> and --post-hook <COMMAND> arguments to the ExecStart line:

ExecStart=/usr/bin/certbot renew --quiet --agree-tos \
             --pre-hook /root/bin/certbot-pre.sh \
             --post-hook /root/bin/certbot-post.sh

Alternate renewal methods

There are some cases in which you might need an alternative to running certbot or certbot-auto as above. For example:

  • You have a web server running on port 80 that you do not want to shut down during renewal
  • You cannot open port 80 during renewal
  • You want a wildcard certificate
  • You want to run the renewal on a different machine than where the certificate will be used

Certbot plugins may help in these cases.

  • The Apache, Nginx, and Webroot plugins integrate with an already running web server to allow renewal without shutting the webserver down.
  • One of the DNS plugins can be used to avoid using port 80, run on a different machine, or obtain a wildcard cert.
  • If all else fails, the manual plugin can be used for manual renewal.

References

Back to top