SearchIn their own words “Let’s Encrypt is a free, automated, and open Certificate Authority. Using Let’s Encrypt services lets anyone acquire valid certificates for TLS/SSL encryption for free.”
In this tutorial, we’ll show you how to use the official certbot tool to obtain a free Let’s Encrypt TLS certificate and use it with Hitch and Varnish.
To complete this guide, you’ll need a couple of things:
A Linux based server with either a privileged account or an account with sudo capabilities. This guide will describe the process on a CentOS7/Red Hat EL7 based system using sudo.
A registered domain name that you own or manage with which to use the certificate
If you don’t own a domain name yet, please take a moment to acquire one from one of the many available registrars. (See Icann.org for an exhaustive list.) Then you must create an A-record with the name of the domain that points to the public IP-address of the host you’re setting up. This guide assumes that an A-record is set up and working, as the way the certificates are acquired relies on this for validation of domain name ownership.
Note: In this guide, we’ll use example.com as the domain name and we will have set up both example.com and www.example.com to point to our host’s public IP address.
You’ll need to install EPEL (Extra Packages for Enterprise Linux) to get both certbot and Hitch. Input the following command:
sudo yum install epel-release
Next, install Varnish Cache 6.0 LTS from the official Varnish Cache repository. If you prefer a manual repository setup over the script based one, follow the guide on Packagecloud.io.
curl -s https://packagecloud.io/install/repositories/varnishcache/varnish60lts/script.rpm.sh | sudo bash
sudo yum install hitch varnish
For Varnish Enterprise customers, install varnish-plus and varnish-plus-addon-ssl . This requires the plus-repositories to be set up in advance:
sudo yum install varnish-plus varnish-plus-addon-ssl
With either Varnish Cache or Varnish Enterprise installed, you can now set up Varnish VCL to pass all incoming certificate server challenge requests through to certbot. This is done by routing all URLs matching the acme-challenge pattern to the certbot listener.
Create a new file /etc/varnish/letsencrypt.vcl with your favorite editor and add this configuration to it:
vcl 4.1;
backend certbot {
.host = "127.0.0.1";
.port = "8080";
}
sub vcl_recv {
if (req.url ~ "^/\.well-known/acme-challenge/") {
set req.backend_hint = certbot;
return(pipe);
}
}
sub vcl_pipe {
if (req.backend_hint == certbot) {
set req.http.Connection = "close";
return(pipe);
}
}
Then include the newly created letsencrypt.vcl file in your main VCL by adding the following include statement after the vcl 4.0; line in /etc/varnish/default.vcl:
include "/etc/varnish/letsencrypt.vcl";
Note: If you’re running Varnish in a load-balanced cluster, the certbot backend definition should point to the master
certbot node. Then certificates need to be copied back around the cluster after renewal and Hitch reloads.
By default, Varnish listens on port 6081. But to accept the challenge request from the Let’s Encrypt system, you need to make it listen on port 80.
Edit the Varnish Enterprise unit file with sudo systemctl edit --full varnish and edit the first -a parameter of the ExecStart variable to listen on port 80.
ExecStart=/usr/sbin/varnishd -a :80 -a localhost:8443,proxy -f /etc/varnish/default.vcl -s malloc,256m
You’re now ready to start the Varnish daemon:
sudo systemctl enable varnish
sudo systemctl start varnish
To make the certificate installs with Hitch easier, add a small script to act as a renewal hook.
This script is called once for each successfully issued certificate.
Create a new file /usr/local/bin/hitch-deploy-hook with your editor and paste this into it:
#!/bin/bash
# Full path to pre-generated Diffie Hellman Parameters file
dhparams=/etc/hitch/dhparams.pem
if [[ "${RENEWED_LINEAGE}" == "" ]]; then
echo "Error: missing RENEWED_LINEAGE env variable." >&2
exit 1
fi
umask 077
cat ${RENEWED_LINEAGE}/privkey.pem \
${RENEWED_LINEAGE}/fullchain.pem \
${dhparams} > ${RENEWED_LINEAGE}/hitch-bundle.pem
Make the script executable:
sudo chmod a+x /usr/local/bin/hitch-deploy-hook
To enable Perfect Forward Secrecy, create a Diffie Hellman Parameter file that Hitch will use. This is done using openssl:
openssl dhparam 2048 | sudo tee /etc/hitch/dhparams.pem
Verify that Hitch is set up with the correct backend in /etc/hitch/hitch.conf:
backend = "[localhost]:8443"
Last, enable the systemd service:
sudo systemctl enable hitch
Note: Don’t start Hitch yet. It will fail since no certificates have been added to its configuration yet. The certificate file will be added in the last step of this tutorial.
The certbot client is installable through the EPEL repository we’ve already configured, so install it now with yum:
sudo yum install certbot
Now we have everything in place to request a certificate from Let’s Encrypt. Use this certbot command to request a certificate:
sudo certbot certonly --standalone --preferred-challenges http \
--http-01-port 8080 -d example.com -d www.example.com \
--deploy-hook="/usr/local/bin/hitch-deploy-hook" \
--post-hook="systemctl reload hitch"
The first time you use certbot, it will ask for your email address and to accept the terms of service. Then the certificate will be obtained after the challenges are completed.
Note: Previous versions of certbot had an option called renew-hook. This has since been replaced by deploy-hook.
You also need to start the certbot-renew timer, which handles automatic certificate renewals once per day:
sudo systemctl enable certbot-renew.timer
sudo systemctl start certbot-renew.timer
The renewal service certbot-renew automatically reuses the settings used with the certbot command and these are saved in the folder /etc/letsencrypt/renewal/.
You should now have a Hitch bundle consisting of the private key, the CA chain, and the pre-generated Diffie Hellman parameter file.
Add the resulting pem-file to your /etc/hitch/hitch.conf using your editor:
pem-file = "/etc/letsencrypt/live/example.com/hitch-bundle.pem"
Now start the Hitch daemon:
sudo systemctl start hitch
Hitch should now start. After opening a browser to the configured hostname, you can confirm that the connection is successfully encrypted using TLS. The certbot renewal process will ensure your certificates are automatically updated and that Hitch will reload when a new certificate is fetched.