Using Certbot and Let's Encrypt on CentOS 6


This is a guide to using Certbot to obtain, install, and renew Let's Encrypt SSL certificates on a CentOS 6 Linux system. This document is a work in progress. In lieu of registering on this wiki, please send comments and corrections to wiki@shaunc.com.

Table of Contents


Background - Let's Encrypt


Why encrypt your website's traffic?
Encryption helps keep your information secure while you're online, and it can prevent malicious users from eavesdropping on your personal and private communications. The most visible type of encryption on the internet is TLS, still commonly referred to as SSL. This encryption protects everyday activities like accessing Gmail, checking your credit card statement, or shopping at your favorite online retailer. Visitors to your cooking blog or your bowling league's website deserve this protection, too. Some search engines even give a rank boost to SSL-enabled sites, so there are multiple benefits to encryption.

Why Let's Encrypt, specifically?
Previously, obtaining an SSL certificate to secure a website could cost hundreds or even thousands of dollars per year. This expense placed HTTPS outside the reach of many operators, especially hobbyist webmasters, leaving loads of data unencrypted in transit and easily intercepted by bad actors. To help mitigate this problem, Let's Encrypt began an initiative to encrypt as much of the internet's traffic as possible. Let's Encrypt has created a framework for providing free SSL certificates to anyone who wants them.

Certbot
In May 2016, the Electronic Frontier Foundation announced a tool called Certbot to help server administrators automate the process of obtaining, installing, and renewing SSL certificates from the Let's Encrypt project. As of June 1 2016, a native package for CentOS 6 was not available. Instead, the EFF has released a shell script wrapper utility called certbot-auto that can be used to manage your certificate(s).

This document will refer to the general program and concept of Certbot using a normal font and a capital C, and to the shell command certbot-auto in lowercase monospace letters.

Prerequisites


System Requirements
This guide makes a few assumptions about your environment. It may help you even if your setup varies, but the instructions were written with the following in mind.

[root@menthol tmp]# cat /etc/redhat-release && httpd -v
CentOS release 6.8 (Final)
Server version: Apache/2.2.15 (Unix)
Server built:   May 11 2016 19:28:33

[root@menthol tmp]# yum install epel-release

[root@menthol tmp]# curl -I "http://menthol.shat.net"
HTTP/1.1 200 OK
Date: Wed, 01 Jun 2016 00:05:43 GMT
Server: Apache/2.2.15 (CentOS)
[...snip...]

[root@menthol tmp]# python --version
Python 2.6.6


A Python version note
Most of the documentation I've seen for Certbot suggests that it requires Python 2.7. As of June 1, 2016, the version of Certbot installed by running certbot-auto works for me under Python 2.6.6, albeit with the deprecation warnings that appear anytime Python 2.6 is run. Installing the IUS python27 packages is still a good idea, but no longer appears to be mandatory.

Step 0: Backup


At this point you should ensure you have a working, usable backup of your current known-good Apache configuration. I keep my config files in version control so it's easy to revert them if I mess up. Whatever backup method you prefer to use, please do so before proceeding.

Step 1: Install mod_ssl


mod_ssl is an Apache module that enables the web server to speak SSL. If it's already installed, i.e. your Apache server is already able to serve HTTPS connections using a self-signed certificate, you can skip on to the next step. If it isn't installed already, install it now.

Installation with yum
[root@menthol tmp]# yum install mod_ssl
[...snip...]
Installed:
  mod_ssl.x86_64 1:2.2.15-53.el6.centos


Configuring mod_ssl
Installing mod_ssl will configure some things automatically. Assuming the default Apache installation layout exists on your system, a new file should have been written to /etc/httpd/conf.d/ssl.conf. Go ahead and inspect that file now in your favorite editor. This configuration file directs Apache to load the shared mod_ssl library and to listen for secure connections on port 443. It also sets up some generally safe options for initializing SSL sessions. You shouldn't have to make any changes to this file right now.

Your default certificate
Additionally, the installer created a default self-signed certificate (probably at /etc/pki/tls/certs/localhost.crt) and told Apache where to find it. This certificate isn't very desirable, though, because nobody really trusts you to sign these things. Your certificate is likely to put up a big warning message anytime someone with a modern browser tries to load your website. A new Let's Encrypt certificate will fix that problem soon. For now, make sure Apache will run correctly with its new mod_ssl module:

Test your mod_ssl installation
[root@menthol tmp]# apachectl configtest
Syntax OK

If you receive parse errors here instead of a "Syntax OK" message, something went wrong. Don't continue, and definitely don't restart Apache, until you can resolve the issues with its configuration. Troubleshooting Apache is beyond the scope of this document, but its errors are normally search engine friendly. When you receive a passing message from apachectl configtest, restart Apache and test it out.

[root@menthol tmp]# apachectl restart


Bring up your browser and try visiting your domain with https:// in front. Remember, the self-signed certificate that got installed with mod_ssl will conjure up a spooky warning in many browsers. That's fine, and you can tell your browser to accept the unknown certificate, or not. All that matters for now is that you got a response, any response, from your server on port 443.

Test your website using regular http:// now, too, just to make sure Apache didn't stop listening on port 80 when it started listening on 443. Stranger things have happened.

Backup your configuration (again)
You'll need to make some changes to /etc/httpd/conf.d/ssl.conf later. Go ahead and make a backup of the copy that was installed with mod_ssl.

Now that your Apache is running and accepting SSL connections, it's time to install Certbot and obtain a real, honest to goodness SSL certificate. This one will be signed by a trusted certificate authority and won't display big warning messages to your site's visitors!

Step 2: Install Certbot using certbot-auto


Clarifying Certbot vs. certbot-auto

Download certbot-auto
certbot-auto must be downloaded from the EFF's website. Because it's just a shell script, you can save it and run it from wherever you like. My personal convention is to have a /home/files directory on my systems where I download sources, compile programs, etc. So I placed certbot-auto there.

[root@menthol files]# cd /home/files && wget https://dl.eff.org/certbot-auto
--2016-05-31 21:04:16--  https://dl.eff.org/certbot-auto
Resolving dl.eff.org... 173.239.79.196
Connecting to dl.eff.org|173.239.79.196|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 43528 (43K) [text/plain]
Saving to: “certbot-auto”

100%[======================================>] 43,528      --.-K/s   in 0.07s

2016-05-31 21:04:16 (632 KB/s) - “certbot-auto” saved [43528/43528]


When you run certbot-auto, it'll install the actual Certbot program and all of its supporting libraries, as well as invoking yum to install any dependencies that aren't already satisfied. On my system, this process created a /root/.local/share/letsencrypt/ directory containing about 35MB of files, including the Certbot program itself at /root/.local/share/letsencrypt/bin/certbot. If your /root is a separate, small partition, please take this into consideration.

Run certbot-auto to install Certbot
Okay, enough warnings and miscellany. It's time to run certbot-auto and get this whole thing installed, right?

[root@menthol files]# chmod a+x certbot-auto
[root@menthol files]# ./certbot-auto
Bootstrapping dependencies for RedHat-based OSes...
[...snip copious lines of yum output...]
Complete!
Creating virtual environment...
Installing Python packages...
Installation succeeded.
/root/.local/share/letsencrypt/lib/python2.6/site-packages/cryptography/__init__.py:26: DeprecationWarning: Python 2.6 is no longer supported by the Python core team, please upgrade your Python. A future version of cryptography will drop support for Python 2.6
  DeprecationWarning
Version: 1.1-20080819
Version: 1.1-20080819
/root/.local/share/letsencrypt/lib/python2.6/site-packages/certbot/main.py:453: DeprecationWarning: BaseException.message has been deprecated as of Python 2.6
  return e.message


Low on RAM? To produce this document, I went through the motions on a VM with 512MB of RAM. The "Creating virtual environment... Installing Python packages... Installation succeded" output took almost 15 minutes to appear. Don't be alarmed if things look stuck.
For brevity's sake, I removed all of yum's output above. Go ahead and accept the installation of whichever dependencies are found. If you just installed the EPEL repository during this tutorial, you may be prompted to accept the repository's signing key; this is normal and you can say yes.

Post-install
When the installation finishes, certbot-auto attempts to build and run a GUI. In my experience, this interface is a bit rough around the edges, as are the "wizards" it drives behind the scenes. They were initially developed for a different Linux distribution and haven't been polished up for CentOS just yet. Let's abandon the dialog that was automatically triggered this time (hit the tab key until < No > is highlighted, then press Enter or Space). Next up, we'll re-run certbot-auto with a command line option to hint at what we want to accomplish.

Step 3-A: Generate your certificate with the GUI


The GUI is optional
If you don't want to use the GUI, or if it's crashing, you can eschew it altogether. The following steps can be accomplished with a single command line given in "Step 3-B: Generate your certificate with the command line." Please read this section anyway even if you don't intend to use the GUI, it contains important information.

Bug warning
To proceed with the GUI, it's a good idea to make sure your terminal window is maximized. There's a bug in the GUI that will cause it to crash if your terminal isn't wide enough. A default sized PuTTY window will experience the crash, but maximizing the window works around it nicely. (If I get around to uploading screenshots here and they look ridiculously oversized, this explains why.)

Also, make sure you know the location of your website's document root. On a default Apache installation, this may be /var/www/html/, but moving it around is fairly common practice. You'll need the full path to this directory.

Now run certbot-auto again, but this time pass along the certonly command line option:

[root@menthol files]# ./certbot-auto certonly


Authentication choices
You should be presented with a dialog asking how you'd like to authenticate with the ACME CA. ACME is the protocol that Certbot and Let's Encrypt use behind the scenes to handle the minting of SSL certificates. Authenticating to the CA is how you prove to Let's Encrypt that you really control the domain you're requesting a certificate for. There are three authentication options available. The easiest and least disruptive of those is choice 2, "Place files in webroot directory (webroot)." Press the down-arrow to highlight option 2 and then press Enter.

Supply an email address
Certbot will now ask you for an email address. Please consider your input here very carefully. Anyone who can access email sent to this account can potentially muck around with the SSL certificate for your domain! If you're acting on behalf of a business, I strongly encourage you to use a role account instead of an individual person's email address; the administrative contact for your company's domain name is likely a good choice. Enter your chosen email address and press Enter.

Terms of Service
Next, you'll be prompted to agree with the Let's Encrypt Terms of Service. After reading all that, grab a fresh cup of coffee to wake back up and then press Enter.

Specify your domain
Finally, it's time to enter the domain name (or subdomain) for which you'd like to request an SSL certificate. Do not include "http://" here. While the GUI supports entering multiple domains (or subdomains) at one time, this guide assumes a single entry for the time being. Enter your domain (or subdomain) and press Enter.

On the next screen, ensure that option 1, "Enter a new webroot" is selected, and press Enter. If your terminal isn't wide enough to accommodate the following dialog, this is where you'll see a crash.

Show Certbot your document root
Now enter the full path to your website's document root, for example /var/www/html. When you press Enter, Certbot will create a new directory well-known/acme-challenge/ inside your document root and write a temporary file there. Certbot then sends your certificate request off to the Let's Encrypt certificate authority server. They, in turn, test for the presence of the temporary file on your website.

Step 3-B: Generate your certificate with the command line


If you've already run the GUI in the previous section, you don't need to run this command. You can use it the next time you need to obtain a new certificate for another domain. If you elected to skip the GUI and use this command instead, please read the previous section anyway, especially the note about your email address.

This command will request a new certificate and authenticate to the certificate authority all in one step:

[root@menthol files]# ./certbot-auto certonly -n --agree-tos --email you@example.com --domain example.com --webroot --webroot-path /var/www/html


Step 4: Backup your certificate files


If all goes well, you should see output similar to this, regardless of whether you ran the GUI or the command line.

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at
   /etc/letsencrypt/live/menthol.shat.net/fullchain.pem. Your cert
   will expire on 2016-08-30. To obtain a new or tweaked version of
   this certificate in the future, simply run certbot-auto again. To
   non-interactively renew *all* of your ceriticates, run
   "certbot-auto renew"
 - If you lose your account credentials, you can recover through
   e-mails sent to [the email address you entered].
 - Your account credentials have been saved in your Certbot
   configuration directory at /etc/letsencrypt. You should make a
   secure backup of this folder now. This configuration directory will
   also contain certificates and private keys obtained by Certbot so
   making regular backups of this folder is ideal.
 - If you like Certbot, please consider supporting our work by:

   Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
   Donating to EFF:                    https://eff.org/donate-le


That entire message is important, but the biggest takeaway right now is that you have a new directory at /etc/letsencrypt which, along with its subdirectories, contain your newly minted SSL certificate files. Make a backup of this directory right now and copy it to another server.

Example tgz and scp offsite
tar czf /tmp/menthol-etc-letsencrypt.tgz /etc/letsencrypt
scp /tmp/menthol-etc-letsencrypt.tgz you@otherhost.example.com:/backups/
rm -f /tmp/menthol-etc-letsencrypt.tgz


Step 5: Install your certificate


Locate your certificate files
With certificate in hand, it's time to configure Apache to begin using it. Certbot has saved several certificate files to your system, presumably in a subdirectory of /etc/letsencrypt/live/ named for your domain. Have a look at the contents of that directory:

[root@menthol files]# ls -la /etc/letsencrypt/live/menthol.shat.net/
total 8
drwxr-xr-x. 2 root root 4096 May 31 22:59 .
drwx------. 3 root root 4096 May 31 22:59 ..
lrwxrwxrwx. 1 root root   40 May 31 22:59 cert.pem -> ../../archive/menthol.shat.net/cert1.pem
lrwxrwxrwx. 1 root root   41 May 31 22:59 chain.pem -> ../../archive/menthol.shat.net/chain1.pem
lrwxrwxrwx. 1 root root   45 May 31 22:59 fullchain.pem -> ../../archive/menthol.shat.net/fullchain1.pem
lrwxrwxrwx. 1 root root   43 May 31 22:59 privkey.pem -> ../../archive/menthol.shat.net/privkey1.pem


Review your backups
Earlier, you should have made or verified that you have a backup of your Apache configuration files. Double check that now, just in to be sure.

Edit ssl.conf
First, locate Apache's SSL configuration file. For a default installation of Apache and mod_ssl, this file probably lives at /etc/httpd/conf.d/ssl.conf, but it may be somewhere else on your system. Open the file in your favorite editor and look around for three directives named SSLCertificateFile, SSLCertificateKeyFile, and SSLCertificateChainFile. These directives, or at least the first two, should currently be pointing at your self-signed certificate files:

[root@menthol conf.d]# grep SSLCert ssl.conf | grep etc
SSLCertificateFile /etc/pki/tls/certs/localhost.crt
SSLCertificateKeyFile /etc/pki/tls/private/localhost.key
#SSLCertificateChainFile /etc/pki/tls/certs/server-chain.crt


Change these so they point to your Let's Encrypt certificate files instead, as follows:

After editing, these lines of your config should look more like this:

[root@menthol conf.d]# grep SSLCert ssl.conf | grep etc
SSLCertificateFile /etc/letsencrypt/live/menthol.shat.net/cert.pem
SSLCertificateKeyFile /etc/letsencrypt/live/menthol.shat.net/privkey.pem
SSLCertificateChainFile /etc/letsencrypt/live/menthol.shat.net/chain.pem


Next, test your Apache configuration and if you get a passing message, restart Apache.

[root@menthol conf.d]# apachectl configtest
Syntax OK
[root@menthol conf.d]# apachectl restart


Bring up your browser and try visiting your domain with https:// in front. This time, you shouldn't get a warning message about an untrusted or suspicious certificate. Your site should load via HTTPS.

Mixed content
If your website includes content from other domains (plugins, widgets, remotely hosted images, etc.) served over unencrypted HTTP connections, you may receive an error in your browser about "mixed content" or "this page contains both secure and unsecure elements." Most large third-party content providers now support HTTPS, and in many cases, turning it on is as simple as editing your HTML so the remote URIs begin with https instead of http. Refer to each content provider's documentation for specifics.

Step 6: Redirecting visitors to your HTTPS website


TODO

Step 7: Dealing with VirtualHosts


TODO

Step 8: Setting up automatic certificate renewal


TODO
There are no comments on this page.
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki