Posts Tagged ‘nginx’

Automating Let’s Encrypt certificates on nginx

February 19th, 2016 No comments

Let’s Encrypt is a new Certificate Authority that provides free SSL certificates. It is intended to be automated, so that certificates are renewed automatically. We’re using Let’s Encrypt certificates for our set of free Calculus practice problems. Our front end is currently served by an Ubuntu server running nginx, and here’s how we have it scripted on that machine. In a future post, I’ll describe how it’s automated on our Docker setup with HAProxy.

First of all, we’re using acme-tiny instead of the official Let’s Encrypt client, since it’s much smaller and, IMHO, easier to use. It takes a bit more to set up, but works well once it’s set up.

We installed acme-tiny in /opt/acme-tiny, and created a new letsencrypt user. The letsencrypt user is only used to run the acme-tiny client with reduced priviledge. In theory, you could run the entire renewal process with a reduced priviledge user, but the rest of the process is just basic shell commands, and my paranoia level is not that high.

We created an /opt/acme-tiny/challenge directory, owned by the letsencrypt user, and we created /etc/acme-tiny with the following contents:

  • account.key: the account key created in step 1 from the acme-tiny README. This file should be readable only by the letsencrypt user.
  • certs: a directory containing a subdirectory for each certificate that we want. Each subdirectory should have a domain.csr file, which is the certificate signing request created in step 2 from the acme-tiny README. The certs directory should be publicly readable, and the subdirectories should be writable by the user that the cron job will run as (which does not have to be the letsencrypt user).
  • private: a directory containing a subdirectory for each certificate that we want, like we had with the certs directory. Each subdirectory has a file named privkey.key, which will be the private key associated with the certificate. To coincide with the common setup on Debian systems, the private directory should be readable only by the ssl-cert group.

Instead of creating the CSR files as described in the acme-tiny README, I created a script called

openssl req -new -sha256 -key /etc/acme-tiny/private/"$1"/privkey.pem -subj "/" -reqexts SAN -config <(cat /etc/ssl/openssl.cnf <(printf "[SAN]\nsubjectAltName=DNS:") <(cat /etc/acme-tiny/certs/"$1"/domains | sed "s/\\s*,\\s*/,DNS:/g")) > /etc/acme-tiny/certs/"$1"/domain.csr

The script is invoked as <name>. It reads a file named /etc/acme-tiny/certs/<name>/domains, which is a text file containing a comma-separated list of domains, and it writes the /etc/acme-tiny/certs/<name>/domain.csr file.

Now we need to configure nginx to serve the challenge files. We created a /etc/nginx/snippets/acme-tiny.conf file with the following contents:

location /.well-known/acme-challenge/ {
    auth_basic off;
    alias /opt/acme-tiny/challenge/;

(The “auth_basic off;” line is needed because some of our virtual hosts on that server use basic HTTP authentication.) We then modify the sites in /etc/nginx/sites-enabled that we want to use Let’s Encrypt certificates to include the line “include snippets/acme-tiny.conf;“.

After this is set up, we created a /usr/local/sbin/letsencrypt-renew script that will be used to request a new certificate:

set +e

# only renew if certificate will expire within 20 days (=1728000 seconds)
openssl x509 -checkend 1728000 -in /etc/acme-tiny/certs/"$1"/cert.pem && exit 255

set -e
DATE=`date +%FT%R`
su letsencrypt -s /bin/sh -c "python /opt/acme-tiny/ --account-key /etc/acme-tiny/account.key --csr /etc/acme-tiny/certs/\"$1\"/domain.csr --acme-dir /opt/acme-tiny/challenge/" > /etc/acme-tiny/certs/"$1"/cert-"$DATE".pem
ln -sf cert-"$DATE".pem /etc/acme-tiny/certs/"$1"/cert.pem
wget -O /etc/acme-tiny/lets-encrypt-x1-cross-signed.pem
cat /etc/acme-tiny/certs/"$1"/cert-"$DATE".pem /etc/acme-tiny/lets-encrypt-x1-cross-signed.pem > /etc/acme-tiny/certs/"$1"/fullchain-"$DATE".pem
ln -sf fullchain-"$DATE".pem /etc/acme-tiny/certs/"$1"/fullchain.pem

The script will only request a new certificate if the current certificate will expire within 20 days. The certificates are stored in /etc/acme-tiny/certs/<name>/cert-<date>.pem (symlinked to /etc/acme-tiny/certs/<name>/cert.pem). The full chain (including the intermediate CA certificate) is stored in /etc/acme-tiny/certs/<name>/fullchain-<date>.pem (symlinked to /etc/acme-tiny/certs/<name>/fullchain.pem).

As-is, the script must be run as root, since it does a su to the letsencrypt user. It should be trivial to modify it to use sudo instead, so that it can be run by any user that has the appropriate permissions on /etc/acme-tiny.

the letsencrypt-renew script is run by another script that will restart the necessary servers if needed. For us, the script looks like this:




set -e

if [ $RV -eq 255 ] ; then
  # renewal not needed
  exit 0
elif [ $RV -eq 0 ] ; then
  # restart servers
  service nginx reload;
  exit $RV;

This is then called by a cron script of the form chronic /usr/local/sbin/letsencrypt-renew-and-restart. Chronic is a script from the moreutils package that runs a command and only passes through its output if it fails. Since the renewal script checks whether the certificate will expire, we run the cron task daily.

Of course, once you have the certificate, you want to tell nginx to use it. We have another file in /etc/nginx/snippets that, aside from setting various SSL parameters, includes

ssl_certificate /etc/acme-tiny/certs/;
ssl_certificate_key /etc/acme-tiny/private/;

This is the setup we use for one of our server. I tried to make it fairly general, and it should be fairly easy to modify for other setups.


This article was originally published at Hubert’s personal website here.

Categories: Hubert C, Linux, Ubuntu Tags: ,

lua + nginx + FastCGI on Debian

June 22nd, 2010 2 comments

(This was originally posted here on my personal blog.)

I’ve recently been doing some testing in lua, and have been comparing the results to the EdgeLink Consulting CMS that we’ve designed in PHP. So far this solution is able to serve substantially more requests per second than our current CMS. However, we haven’t really spent much time optimizing the CMS. The goal is to have a working copy first before any optimizations are done. We’ve also been working on some eCommerce modules for the platform.

With all that being said, I’d like to post a quick tutorial on how I got this setup. It was quite the task. Although there was a tutorial I found to do the same task, it was a little bit confusing. My tutorial will have a lot of the same steps, with some minor adjustments. This tutorial is written at an intermediate level. Some trivial steps have been omitted.

NOTE: This has been tested with Debian 5.0.4 (Stable)

  1. Install nginx

    apt-get install nginx

    We’ll have to do some modifications later on to add the FastCGI handler. For simplicity we will keep the web path to “/var/www/nginx-default” and listen on port 8081 in case you have another webserver running on port 80.

  2. Install lua 5.1 (and WSAPI libraries)

    apt-get install lua5.1 liblua5.1-wsapi-fcgi-0 liblua5.1-coxpcall0 liblua5.1-filesystem0

    apt-get install liblua5.1-wsapi-doc

    Can’t do much testing without this. Note: The second line is not necessary if you are running Debian testing, and get the liblua5.1-wsapi-fcgi-1instead.

    EDIT: You’ll notice that I added in liblua5.1-filesystem0. Steve pointed out that there is a bug in liblua5.1-wsapi-fcgi-0. It doesn’t include it as a dependency. He reported this as a bug here, and it was fixed in liblua5.1-wsapi-fcgi-1.

  3. Install spawn-fcgiIf you’re running Debian testing you may be able to get spawn-fcgi through the distribution, however, I just downloaded it and compiled from source.

    tar -xzvf spawn-fcgi-1.6.3.tar.gz
    cd spawn-fcgi-1.6.3.tar.gz
    make install

  4. Create a FastCGI Socket

    spawn-fcgi -F 4 -u www-data -s /var/run/nginx-fcgi.sock -P /var/run/ — /usr/bin/wsapi.fcgi

    For the sake of simplicity, we will just spawn it manually for now. If you’re feeling crafty you can add the above line to the start condition in/etc/init.d/nginx, and the line below to the stop condition. You can add both of them to restart.

    cat /var/run/ | xargs -n 1 kill

  5. Create a lua file in /var/www/nginx-default/In this tutorial, use hello.lua. You can change this to whatever, you want but just make sure you make the modification in the nginx configuration below as well.
  6. Edit /etc/nginx/sites-available/defaultNow let’s add the code that will point nginx to the correct file. For simplicity, we will simply point it to hello.lua. You can change this to anything, or simply modify the code to accept any *.lua file, as seen in the tutorial listed above. Here is the top of my default file:

    listen   8081 default;
    server_name  localhost;
    access_log  /var/log/nginx/localhost.access.log;

    location / {
    fastcgi_pass    unix:/var/run/nginx-fcgi.sock;
    fastcgi_param   SCRIPT_FILENAME “/var/www/nginx-default/hello.lua”;
    fastcgi_param   PATH_INFO       $request_uri;
    fastcgi_param   QUERY_STRING    $query_string;
    fastcgi_param   REQUEST_METHOD  $request_method;
    fastcgi_param   CONTENT_TYPE    $content_type;
    fastcgi_param   CONTENT_LENGTH  $content_length;

  7. Restart nginx

    /etc/init.d/nginx restart

  8. Visit http://localhost:8081/Congratulations! You should now see hello.lua.

If you have any problems, post in the comments. Stay tuned for more related posts.