nginx-letsencrypt

Simplify the process of setting up nginx with letsencrypt in a configuration managed environment.

Motiviation

Letsencrypt's certbot utility makes the process of obtaining domain validated TLS certificates a breeze. It implements the ACME client protocol and offers multiple options to perform said domain validation. Unfortunately however, none of the options provided enable streamlined issuing of certificates in a managed nginx configuration environment:

• The built-in --nginx flag works well, however it mutates nginx configuration files which doesn't play nice with configuration management tools that assume immutable files.

• The manual "certonly" modes can be setup with immutable configuration, however they require either manual bootstrapping or additional configuration:

• standalone: requires shutting down nginx (for issuing and renewal)
• dns verification: requires the server to have access to DNS configuration. This requires isolation of DNS management to domains associated with a given server.
• webroot: does not require a server shutdown and offers isolation, however it requires manual intervention to bootstrap a system with an initial certificate, since nginx will not start if the ssl directive is set and there are no certificates. (Therefore, one would be required to first configure the webroot, run certbot and then add an ssl entry).

The solution proposed by nginx-letsencrypt is to combine the webroot "certonly" modus operandi with self-signed bootstrapping certificates and an includable ssl configuration file.

Overview

nginx-letsencrypt comes in two parts: an nginx configuration file "letsencrypt" that should be included by server blocks that enable HTTPS, and a shell-script "nginx-letsencrypt" that wraps certbot. Server configuration blocks (in /etc/nginx/sites-enabled) include the letsencrypt ssl configuration file and the wrapper script takes care of issuing a certificate for all domains use by virtual hosts.

Usage

A certificate will be issued for all server names defined in server blocks that contain 'include letsencrypt'. Obtaining certificates requires the following steps:

1. Add include letsencrypt; to all server blocks that should enable HTTPS.
2. Run nginx-letsencrypt.

Note regarding certificate renewal: certbot will automatically add a cron entry to renew certificates. No manual intervention is needed.

Example

Given the following server block configuration in /etc/nginx/sites-enabled/server:

server {
    server_name foo.example.org bar.example.com;
    listen 80;
    listen [::]:80;
    include letsencrypt;

    root /srv/www;
    location / {
        index index.html;
    }
}

Running nginx-letsencrypt will issue certificates for "foo.example.org" and "bar.example.com".

Notes

nginx-letsencrypt is a thin wrapper around certbot. It will read /etc/letsencrypt/cli.ini for settings such as email.

Copying

This project is released under the terms of the GPL license. See LICENSE for details.