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.

Enterprise Linux 7+¶

This section contains instructions for Enterprise Linux 7 and newer operating systems, using systemd timers and certbot from an RPM.

Installation and Obtaining the Initial Certificate¶

Install the certbot package (available from the EPEL 7 repository):
```
[email protected] # yum install certbot
```
Stop services running on port 80 if there are any.

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

[email protected] # certbot certonly --standalone --email <ADMIN_EMAIL> -d <HOST>

Set up hostcert/hostkey links:

[email protected] # ln -sf /etc/letsencrypt/live/*/cert.pem /etc/grid-security/hostcert.pem
[email protected] # ln -sf /etc/letsencrypt/live/*/privkey.pem /etc/grid-security/hostkey.pem
[email protected] # chmod 0600 /etc/letsencrypt/archive/*/privkey*.pem

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:

[email protected] # 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:

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

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
```

Update the systemd manager configuration:

[email protected] # systemctl daemon-reload

Start and enable the certbot timer:

[email protected] # 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 [email protected]

Then call certbot as follows:

[email protected] # 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

Enterprise Linux 6¶

This section contains instructions for Enterprise Linux 6, using cron and the certbot-auto script.

Installation and obtaining the initial certificate¶

Download and install certbot-auto as described in the install instructions.
Stop services running on port 80 if there are any.

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

[email protected] # certbot-auto certonly --standalone --email <ADMIN_EMAIL> -d <HOST>

Set up hostcert/hostkey links:

[email protected] # ln -sf /etc/letsencrypt/live/*/cert.pem /etc/grid-security/hostcert.pem
[email protected] # ln -sf /etc/letsencrypt/live/*/privkey.pem /etc/grid-security/hostkey.pem
[email protected] # chmod 0600 /etc/letsencrypt/archive/*/privkey*.pem

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:

[email protected] # certbot-auto 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-auto can verify the host.

Automating renewals using cron¶

To automate renewal using cron, create a cron job in /etc/cron.d/certbot-renew with the following contents:

* */2 * * * root /usr/local/bin/certbot-auto renew --quiet --agree-tos --no-self-upgrade

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

Pre- and post-renewal hooks¶

certbot-auto 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-auto 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 [email protected]

Then call certbot-auto as follows:

[email protected] # certbot-auto renew --pre-hook /root/bin/certbot-pre.sh \
                               --post-hook /root/bin/certbot-post.sh

For automated renewal, edit the /etc/cron.d/certbot-renew file that you created above and add the --pre-hook <COMMAND> and --post-hook <COMMAND> arguments:

* */2 * * * root /usr/local/bin/certbot-auto renew --quiet --agree-tos --no-self-upgrade --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.

Note

The DNS plugins do not work with certbot-auto. You will need to use one of the Docker containers if you are using Enterprise Linux 6.

References¶

Useful OpenSSL commands (from NCSA) - e.g. how to convert the format of your certificate.
Official Let's Encrypt setup guide.
Another Let's Encrypt setup reference. Under Getting your host certificate, we follow the first "Setting up" section.

Requesting Host Certificates Using Let's Encrypt¶

Enterprise Linux 7+¶

Installation and Obtaining the Initial Certificate¶

Renewing Let's Encrypt host certificates¶

Automating renewals using systemd timers¶

Pre- and post-renewal hooks¶

Example¶

Enterprise Linux 6¶

Installation and obtaining the initial certificate¶

Renewing Let's Encrypt host certificates¶

Automating renewals using cron¶

Pre- and post-renewal hooks¶

Example¶

Alternate renewal methods¶

References¶

Requesting Host Certificates Using Let's Encrypt ¶