janeczku / Haproxy Acme Validation Plugin

HAProxy ACME domain validation plugin

HAProxy plugin implementing zero-downtime ACME http-01 validation for domains served by HAProxy instances. The plugin leverages HAProxy's Lua API to allow HAProxy to answer validation challenges using token/key-auth files provisioned by an ACME client to a designated directory.

Compatible ACME clients

The plugin is compatible with ACME clients supporting webroot authentication for http-01 challenges.

• Official Let's Encrypt client
• lego ACME client (coming soon!)

Features

Zero-Downtime

No need to take HAProxy offline to issue or reissue certificates.

Self-Contained

No need to leverage a backend webserver for the trivial task of serving a key authorization file once every three months per domain.

Installation instructions

Prerequesites

You need to be rolling HAProxy version 1.6.0 or later with Lua support enabled. To check if your HAProxy binary was compiled with Lua support run the following command:

haproxy -vv

If there is a line similar to this you are good to go:

Built with Lua version

If your binary doesn't come with Lua bindings, you can download Debian/Ubuntu packages of the latest v1.6 release from the Debian HAProxy packaging team.

Installation

Download the zip/tar.gz archive corresponding to your version of HAProxy from the releases page and extract the files. Copy acme-http01-webroot.lua to a location accessible by HAProxy. If you don't run HAProxy chrooted (chroot config option), you need to edit the plugin and set the non_chroot_webroot value to the path of the directory you want to use as your web root.

To activate the plugin you just need to add three lines to your haproxy.cfg:

In the global section insert

lua-load /etc/haproxy/acme-http01-webroot.lua

to invoke the Lua plugin.

In the frontend section serving the domain(s) for which you want to create/renew certificates insert:

acl url_acme_http01 path_beg /.well-known/acme-challenge/
http-request use-service lua.acme-http01 if METH_GET url_acme_http01

This will pass ACME http-01 validation requests to the Lua plugin handler.

Note: ACME protocol stipulates validation on port 80. If your HTTP frontend listens on a non-standard port, make sure to add a port 80 bind directive.

Finally, soft-restart HAProxy (see below for instructions) to apply the updated configuration.

Workflow

A complete workflow for issuing certificates using the Let's Encrypt CA for domains served by HAProxy.

An example minimal haproxy.cfg for this workflow is available here.

1. Prepare HAProxy

First, enable the acme-http01-webroot.lua plugin in your haproxy.cfg as described above.

Letsencrypt stores the certificate, chain and private key in /etc/letsencrypt/live/domain.tld/. HAProxy requires a PEM file that includes the certificate and corresponding private key. We need to set the crt directive in the haproxy.cfg to point to the PEM file which we will create later in the process.

...
frontend https
    bind *:443 ssl crt /etc/letsencrypt/live/www.example.com/haproxy.pem
...

2. Install letsencrypt client

Follow the official guide to install the client.

3. Issue certificate

We are ready to create our certificate. Let's roll!

We invoke the letsencrypt client with the webroot method. --webroot-path must be set to the value of the chroot parameter in your haproxy.cfg. If you are not running HAProxy chrooted you need to set it to the value of the non_chroot_webroot parameter configured in the Lua plugin.

$ sudo ./letsencrypt-auto certonly --text --webroot --webroot-path \
  /var/lib/haproxy -d www.example.com --renew-by-default --agree-tos \
  --email [email protected]

Next, concat the certificate chain and private key to a PEM file suitable for HAProxy:

$ sudo cat /etc/letsencrypt/live/www.example.com/privkey.pem \
  /etc/letsencrypt/live/www.example.com/fullchain.pem \
  | sudo tee /etc/letsencrypt/live/www.example.com/haproxy.pem >/dev/null

Whohaaa! Done.

4. Soft-restart HAProxy

We want HAProxy to reload the certificate without interrupting existing connections or introducing any sort of down-time.

Depending on your environment this can be accomplished in several ways:

Ubuntu/Debian command

$ sudo service haproxy reload

Generic command

$ haproxy -f /etc/haproxy/haproxy.cfg -p /var/run/haproxy.pid \
  -sf $(cat /var/run/haproxy.pid)

or if you are up for some bash-ism:

$ eval $(xargs -0 < /proc/$(pidof haproxy)/cmdline | \
  awk -F '-sf' '{print $1}') -sf $(pidof haproxy)

Certificate renewal

To renew a certificate manually just repeat steps No. 3 and 4.

Automatic renewal

To automate renewal of certificates you can use this handy bash script: cert-renewal-haproxy.sh.

The script automates the following steps:

• Check the expiry of all the certificates under /etc/letsencrypt/live
• Renew certificates that expire in less than 4 weeks
• Create the haproxy.pem files
• Soft-restart HAProxy.

Use it in a cron job like this for weekly runs:

$ sudo crontab -e

5 8 * * 6 /usr/bin/cert-renewal-haproxy.sh