Set up Let’s Encrypt with NGINX web server with certbot webroot plugin

Introduction

This is one (of many) methods to speed up creating free SSL certificates with Let's Encrypt.

It configures the NGINX web server to serve /.well-known/acme-challenge/ for each domain. This path is used by the webroot plugin.

We’ll need to make a directory to servie the challenge files from, we’ll call this /home/www/letsencrypt from now on, and we’ll need to make sure this is set up with suitable permissions such that

• NGINX can serve these files to the public
• whomever is running certbot-auto can write to the directory

In NGINX’s config, we want to add the following to each server block configuration:

location ^~ /.well-known/acme-challenge/ {
    default_type "text/plain";
    root /home/www/letsencrypt;
}

When this is in place, whenever a HTTP client makes a request to /.well-known/acme-challenge/TOKEN for the your domain, it will serve the file from /home/www/letsencrypt/TOKEN. This is how the HTTP-01 challenge works.

Generally, adding this in /etc/nginx/global/global.conf and including this file (usually already done by a default install) in each *.conf file in /etc/nginx/conf.d/ is recommended.

The way I normally do this is to create a file /etc/nginx/global/letsencrypt.conf with:

location ^~ /.well-known/acme-challenge/ {
    default_type "text/plain";
    root /home/www/letsencrypt;
}

Then in each server block, for the port 80 listener, I have:

server {
    listen 80;
    server_name www.MYDOMAIN.com;
    include global/letsencrypt.conf;
    location / {
        return 301 https://$server_name$request_uri;
    }
}

This is a normal practice, that I redirect HTTP requests to HTTPS. However, any HTTP request to /.well-known/acme-challenge/ (used by the HTTP-01 challence), is served from /home/www/letsencrypt

Install certbot

Install via snapd

Install certbot - for most distributions, it requires snapd

Ensure that your version of snapd is up to date

snap install core
snap refresh core

Remove old certbot-auto, by running these as needed, as needed by your distribution

apt-get remove certbot
dnf remove certbot
yum remove certbot

Install certbot

snap install --classic certbot
ln -s /snap/bin/certbot /usr/bin/certbot

Install by native package manager

Some distributions may have their own certbot distribution available by their package manager. In which case you can use yum install certbot or apt-get install certbot.

Install by Python pip

Refer to certbot instructions.

Add a certificate for a domain

certbot certonly --webroot -w /home/www/letsencrypt -d domain.com

You need to make sure certbot has write permissions to the direction given with the -w parameter.

If you want to do a dry run, to check whether the HTTP-01 challenge is successful or not, without actually creating a certiticate - you can run:

certbot certonly --webroot -w /home/www/letsencrypt -d domain.com --dry-run

Configure NGINX server blocks

In each domain’s server block add the follow, but use your own domain name for the certificate paths.

listen               443 ssl;
ssl_certificate      /etc/letsencrypt/live/domain.com/fullchain.pem;
ssl_certificate_key  /etc/letsencrypt/live/domain.com/privkey.pem;
include              ssl/ssl.conf;

In ssl/ssl.conf we have:

ssl_session_timeout       5m;
ssl_protocols             TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers               "ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS";
ssl_prefer_server_ciphers on;
ssl_session_cache         shared:SSL:10m;
ssl_dhparam               /etc/nginx/ssl/dhparams.pem;

The above SSL config is my personal preference, but you can adjust to your liking.

If you don't have a DH parameters file configured, you can generate one with

openssl dhparam -out /etc/nginx/ssl/dhparams.pem 2048

Renew all certs if near expiry

For domains which have previously had a certificate issued, you can renew them with

certbot renew

You don't need to use --webroot -w /home/www/letsencrypt again.

This can be added as a cron job.

00 2 * * * root /usr/local/bin/certbot renew 2> /dev/null

If you wish the automation to apply for a single domain only, use:

00 2 * * * root /usr/local/bin/certbot renew --cert-name NAME 2> /dev/null

Note that this will renew the certificates, but your NGINX web server will not know they have renewed. You need to reload NGINX's config files to make sure new certificates have been read. You could make a cron job to do this, some short time after the renewal attempt:

15 2 * * * root nginx -s reload 2> /dev/null

Certificate names are usually the same as the domain name, however this may not always be the case. You can check your certificate names with:

certbot certificates

To test configuration and check that HTTP-01 challenge and verification will work. This is a a good idea if you've been editing the NGINX config files where you could have broken something.

certbot renew --dry-run

This will check for all domains configured for certbot

Other useful certbot commands

Deleting certificates

certbot delete --cert-name DOMAIN

Viewing installed certificates

certbot certificates