Wiki source for UsingCertbotAndLetsEncryptOnCentos6


Show raw source

======Using Certbot and Let's Encrypt on ""CentOS"" 6 ======

This is a guide to using [[https://certbot.eff.org|Certbot]] to obtain, install, and renew [[https://letsencrypt.org/|Let's Encrypt]] SSL certificates on a [[https://www.centos.org/about/|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.

{{{toc}}}

====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 [[https://en.wikipedia.org/wiki/Transport_Layer_Security|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 [[https://eff.org|Electronic Frontier Foundation]] announced a tool called [[https://certbot.eff.org|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.


~- You're running ""CentOS"" 6 and Apache 2.x
~ %%[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%%
~- You have root shell access to your server
~- You manage (most) packages on your server with ##yum##
~- You have the [[https://fedoraproject.org/wiki/EPEL|Extra Packages for Enterprise Linux]] repository (EPEL) installed, as there are some dependencies that live there
~ %%[root@menthol tmp]# yum install epel-release%%
~- You have either a fully qualified domain name or a subdomain (Certbot and Let's Encrypt will work with either)
~- Apache is already configured and serving your website over normal HTTP
~ %%[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...]%%
~- You have Python 2.6 or better installed
~ %%[root@menthol tmp]# python --version
Python 2.6.6%%
~- You can create directories and write files into your website's document root (##public_html##, ##htdocs##, or similar)

==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 [[https://ius.io/|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==
~-Certbot is a Python program that will be installed on your system. This is the program that interacts directly with the Let's Encrypt certificate authority (usually over the network, although there are provisions for doing things offline). For the purposes of this guide, you won't be running Certbot directly.
~- ##certbot-auto## is a shell script provided by EFF that automates many of the steps involved in using Certbot. It will install Certbot and its dependencies for you, step you through the process of obtaining your SSL certificate(s), and handle automated renewal of your certificate(s). It also automatically updates Certbot (and itself), so you always have the most recent version. This is the tool you'll be running.

==Download certbot-auto==
##certbot-auto## must be downloaded [[https://dl.eff.org/certbot-auto|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 [[https://github.com/certbot/certbot/issues/2787|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 [[https://letsencrypt.org/documents/LE-SA-v1.0.1-July-27-2015.pdf|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:

~- ##""SSLCertificateKeyFile""## - For all Apache 2.x versions, this will be ##privkey.pem##.
~- ##""SSLCertificateFile""## - For Apache versions under 2.4.8, use ##cert.pm##. For Apache 2.4.8 or newer, use ##fullchain.pem##.
~- ##""SSLCertificateChainFile""## For Apache versions under 2.4.8, use ##fullchain.pem##. For Apache 2.4.8 or newer, you can leave this directive unset (commented out).

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
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki