Using LetsEncrypt
LetsEncrypt is a fantastic project and this site is currently using a LetsEncrypt cert. They give you a free short term lease cert, 90 days to be precise. After the 3 months you must renew the cert. In this post I'll describe briefly my experience installing one of their certs. LetsEncrypt does offer to automatically install the cert to your server of choice, but we'll be skipping over that in favor of manual installation.
Installation
As per their instructions download and run letsencrypt-auto -- You can do this by cloning their repo and checking out the latest stable tag. This is the same approach taken by many other projects, like RVM. This type of software installation says to the user "Hey download this script and run it, I'll take care of everything for you".
Running letsencrypt-auto will install a number of dependencies and python modules. Depending on how many dependencies you have already met and your hardware, this is going to take a bit of time. Take a coffee break or stick your head out the window.
The automatic installer failed for me and if you do not have enough available memory it may fail for you. I should note that I was running this on the cheapest available instance from Digital Ocean with only 512MB of memory. This was the only dent in an otherwise smooth installation process and it has nothing to do with LetsEncrypt or their installer. So, to reiterate, if you do not have enough available memory, the installation will fail -- particularly at building the python cryptography library.
So if you're short on memory, take a moment to stop your memory hogging processes and you should be okay to re-run the installer.
Acquiring the Cert
At this point you will find LetsEncrypt installed to the directory ~/.local/share/letsencrypt and you'll find the letsencrypt binary at the location: ~/.local/share/letsencrypt/bin/letsencrypt
LetsEncrypt wants to automate as much of the process of installing a cert as they possibly can. And in this effort, they have created a plugin system for installing the cert on particular servers like Apache and Nginx. This is conceptually a nice idea but I'm not sure how well the automatic installer actually works.
Unfortunately for those of us that use Nginx, This is what the LetsEncrypt docs have to say about Nginx Support:
The Nginx plugin is still experimental…
So let's just go with manual cert installation, which generates the public and private cert files and leaves the rest up to you.
During manual installation you'll fill-in some information. The installer program will send all of this up to the LetsEncrypt CA Server. Lastly the program will ask you to expose a path with a randomly generated token assigned to your request. The program will ask you to make sure that a verification url is reachable from their server. This last requirement is absolutely crucial in their server verifying your identity.
Below is an example of the path expected to be available during the verification step:
/.well-known/acme-challenge/HGr8U1IeTW4kY_Z6UIyaakzOkyQgPr_7ArlLgtZE8SX
To learn about ACME and the ACME challenge, take a look at the document Automatic Certificate Management Environment.
If you've ever signed up for Google WebMaster Tools and had to verify ownership of a domain, it's a bit like that.
Essentially, this verification URL boils down to
/.well-known/acme-challenge/<verification-token>
The fact that this URL needs to be exposed is the only reason their installation instructions ask you to stop your server or any other process bound to port 80. If you have important services running on that server, you don't actually need to shutdown your server, you can simply configure server to serve the verification url -- that way your critical webserver can continue running.
But, let's imagine you're not running anything important, and simply stop your current webserver (or any other service bound to port 80) and proceed with using LetsEncrypt to install your brand new cert.
So make sure nothing is bound to port 80 and we can finally acquire this cert.
Run:
~/.local/share/letsencrypt/bin/letsencrypt --manual -d mydomain.com
If you want to use the same cert for multiple domains you can specify more than one domain like so:
~/.local/share/letsencrypt/bin/letsencrypt --manual -d mydomain.com -d www.domain.com
We will continue with an example of one domain for the sake of this guide.
The manual cert installer will now display something like this:
Processing /etc/letsencrypt/renewal/mydomain.com.conf
Make sure your web server displays the following content at
http://fahmidur.us/.well-known/acme-challenge/<TOKEN_FILENAME> before continuing:
<TOKEN_FILECONTENT>
If you don't have HTTP server configured, you can run the following
command on the target server (as root):
mkdir -p /tmp/letsencrypt/public_html/.well-known/acme-challenge
cd /tmp/letsencrypt/public_html
printf "%s" <TOKEN_FILECONTENT> > .well-known/acme-challenge/<TOKEN_FILENAME>
# run only once per server:
$(command -v python2 || command -v python2.7 || command -v python2.6) -c \
"import BaseHTTPServer, SimpleHTTPServer; \
s = BaseHTTPServer.HTTPServer(('', 80), SimpleHTTPServer.SimpleHTTPRequestHandler); \
s.serve_forever()"
Press ENTER to continue
That last part about running your own server, is a bit long only because it is trying to be robust for whatever version of python you have installed. If you have ruby installed you can simply navigate to the public_html directory and run
ruby -run -e httpd . -p 80
Much smaller.
Renewing Your Certs
If you started using letsencrypt a while back, and you're only renewing now approximately 3 months later, you'll need to update your letsencrypt. Navigate to letsencrypt repo, pull, and checkout the latest stable tag. In my case that is LetsEncrypt v0.4.1. Running LetsEncrypt auto again will automatically upgrade your installed copy at /root/.local/share/letsencrypt.
To Watch Out For
It is possible that you have a more up to date version of python than is supported by your package manager. In that case, letsencrypt-auto will fail while trying to install python-dev. Rather than downgrade my version of python, I simply removed the python-dev line from the function BootstrapDebCommon() in letsencrypt-auto.
Also if you already have virtual-env installed by other means, you can remove the virtualenv line as well from BootstrapDebCommon()
I wish LetsEncrypt didn't try to install everything for you, I think it should just check if it has the minimum scripting requirements to do what it does and then run -- but that notion probably comes from my not realizing how complex of a project it is.
Lastly to renew, navigate to /root/.local/share/letsencrypt and run ./letsencrypt renew --manual-public-ip-logging-ok.
That will use the same approach that you used when first creating the certs, for every cert that you have installed. Go through the prompts and all will be well.
That's all for now.