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
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¶
certbotpackage (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:
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.servicewith 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
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
--pre-hook <COMMAND> for a command or script to run before renewal,
--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.
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:
#!/bin/bash condor_ce_off -daemon CEVIEW
#!/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]
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
--post-hook <COMMAND> arguments to the
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-auto as above.
- 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.