dehydrated quickstart

A simple site certificate with Let's Encrypt, dehydrated, and Apache

I didn’t like the look of installing the official Let’s Encrypt client and all of its dependencies on Slackware. Thankfully, there are a number of alternative ACME-protocol clients.

dehydrated appeals to me because it’s a Bash shell script and it’s easy to set up. However, getting started using the README and other documentation is a bit challenging to piece together.

So I’m documenting my process for my future reference and for anyone else who would like to get going quickly with a simple example.

Install

If you’re running Slackware like me, then you’ll be happy to know there’s a SlackBuild for dehydrated. Installation looks like this:

$ sudo sbopkg -i dehydrated
$ which dehydrated
/usr/bin/dehydrated

Otherwise, you can clone the repo and install manually, which would look something like this (untested):

$ git clone https://github.com/lukas2511/dehydrated.git
$ sudo cp dehydrated/dehydrated /usr/bin/

Configuration

Dehydrated looks for a config file in several locations, including /etc/dehydrated/config. Let’s create one:

# cat > /etc/dehydrated/config
CA="https://acme-staging.api.letsencrypt.org/directory"
CHALLENGETYPE="http-01"
WELLKNOWN="/var/www/htdocs/.well-known/acme-challenge"
CONTACT_EMAIL="you@example.com"

Let’s take this config line-by-line:

  • CA is the certificate authority URL - notice that we’re going to start with "staging" to test our setup before we move to the real deal
  • CHALLENGETYPE is the method we want to use to verify we own this domain. http-01 will look for a specific URL on our web server. The alternative is dns-01, which requires us to edit our DNS zone file
  • WELLKNOWN is used in conjunction with the http-01 challenge type. It is the directory to which dehydrated should write the challenge file. In our simple example, we’re getting a certificate for one domain with a single web root (at /var/www/htdocs/). The .well-known/acme-challenge URL is where Let’s Encrypt will be looking, so this setting will put the file right where its expecting it. Getting certificates for more than one domain on the same server will require just a little bit more work
  • CONTACT_EMAIL is where Let’s Encrypt will send an expiration email if your certificate is about to expire and hasn’t been renewed

domains.txt

We also need to specify which domains for which to request certificates. There’s another file for that:

# cat > /etc/dehydrated/domains.txt
example.com www.example.com

That one’s easy. You can have just a single domain name, or you can add some subdomains on the same certificate by putting them on the same line (example.com www.example.com). Blank lines and comments (#) are ignored.

If you have multiple domains on this server, you can specify them on separate lines. (You’ll probably also need to do some server trickery to get them all to work with the WELLKNOWN path above.)

Prepare for the http-01 challenge

To meet Let’s Encrypt’s verification challenge, dehydrated is going to try to write a specifically-named file to our above WELLKNOWN path. The path will need to exist:

$ mkdir -p /var/www/htdocs/.well-known/acme-challenge

We also need Apache to be able to read the file in order to serve it for the challenge:

$ sudo chgrp -R apache /var/www/htdocs/.well-known

Do a test run

Now we can run dehydrated:

$ sudo dehydrated -c

The -c option stands for "cron" and is pretty much the dehydrated universal register/renew operation (it’s also how you’ll be running the command as a cron job to automatically renew later).

If the challenge fails, you may need to check your Apache configuration. For example, I’d forgotten to add a <VirtualHost> directive entry for the www subdomain at www.saltwheel.org. The challenge had passed for saltwheel.org, but all I kept seeing was the error and assumed I’d missed a dehydrated configuration parameter somewhere.

If all goes well, there will be no errors and you will actually have a test/staging certificate from Let’s Encrypt!

Get a real certificate

Let’s change the CA URL from "staging" to the production API (acme-v01):

$ sudo sed -i 's/acme-staging/acme-v01/' /etc/dehydrated/config

All the sed command above did was change the config line:

FROM: CA="https://acme-staging.api.letsencrypt.org/directory"
TO:   CA="https://acme-v01.api.letsencrypt.org/directory"

(Feel free to make the change in your favorite text editor.)

We’re almost ready to run dehydrated again. But if we do, it will see that we already have a certificate (from staging) and won’t request a new one. (Try it and see!)

To get our real certificate, we’ll need to delete the test one:

$ sudo rm -rf /etc/dehydrated/certs/*

Now you’re ready for the real certificate:

$ sudo dehydrated -c

Since it worked with staging, you should have no problem with production.

You now have a new directory containing the certificates for your domain(s):

$ sudo tree /etc/dehydrated/
/etc/dehydrated/
|-- accounts
|-- certs
|   |-- example.com
|   |   |-- cert-000000000.csr
|   |   |-- cert-000000000.pem
|   |   |-- cert.csr -> cert-000000000.csr
|   |   |-- cert.pem -> cert-000000000.pem
|   |   |-- chain-000000000.pem
|   |   |-- chain.pem -> chain-000000000.pem
|   |   |-- fullchain-000000000.pem
|   |   |-- fullchain.pem -> fullchain-000000000.pem
|   |   |-- privkey-000000000.pem
|   |   `-- privkey.pem -> privkey-0000000000.pem
|   `-- test
|-- config
`-- domains.txt

Serious Apache configuration is beyond this article, but here’s the basic idea of what you want to have to use your new certificate in /etc/httpd/httpd.conf (or wherever you and your distro like to store Apache’s configuration):

<VirtualHost www.example.com:443 example.com:443>
	ServerName example.com
	SSLEngine on
	SSLCertificateFile /etc/dehydrated/certs/example.com/cert.pem
	SSLCertificateKeyFile /etc/dehydrated/certs/example.com/privkey.pem
	SSLCertificateChainFile /etc/dehydrated/certs/example.com/fullchain.pem
</VirtualHost>

Restart Apache to load the new directives:

$ sudo /etc/rc.d/rc.httpd restart

The above works in Slackware; you may need to look up the correct way to restart Apache on your distro of choice.

Congratulations, you should now have a secure domain reachable at https://<your domain>.