• Stars
    star
    293
  • Rank 141,748 (Top 3 %)
  • Language
    Shell
  • License
    MIT License
  • Created about 9 years ago
  • Updated over 5 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

🍀 Zero-downtime ACME / Let's Encrypt certificate issuing for HAProxy

HAProxy ACME domain validation plugin

Latest Version License

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.

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

More Repositories

1

calibre-web

📚 Web app for browsing, reading and downloading eBooks stored in a Calibre database
Python
11,592
star
2

go-dnsmasq

🐬 Lightweight caching DNS server/forwarder
Go
401
star
3

rancher-letsencrypt

🐮 Rancher service that obtains and manages free SSL certificates from the Let's Encrypt CA
Go
326
star
4

docker-machine-vultr

Ⓜ️ Docker Machine driver for Vultr Cloud
Go
193
star
5

docker-dropbox

🐳 Dropbox in a Docker image. This works.
Shell
148
star
6

go-ipset

🔥 Go bindings for the IPtables ipset http://ipset.netfilter.org userspace utility
Go
119
star
7

docker-alpine-kubernetes

:octocat: Alpine Linux base image with support for DNS service discovery in Docker clusters
Shell
112
star
8

keepalived-ingress-vip

💓 HA/IP failover solution for on-premises and bare-metal Kubernetes clusters.
Smarty
53
star
9

powerdns_exporter

📈 Prometheus metrics exporter for PowerDNS
Go
34
star
10

go-rancher-gen

🐮 Generate configuration files using templates and Rancher Metadata
Go
32
star
11

docker-calibre-web

🐳 Docker image for Calibre Web
Shell
32
star
12

terraform-rancheros-vmware

HCL
23
star
13

go-spinner

GO spinner / activity indicator for command line applications
Go
21
star
14

docker-nfs-ganesha

🐳 🚢 NFS-Ganesha Docker Image
Shell
16
star
15

docker-shipyard-armv7

🐳 Shipyard Docker management for Raspberry Pi 2 / Scaleway C1
JavaScript
11
star
16

docker-alpine-haproxy

🐳 Haproxy docker image based on Alpine Linux
Makefile
10
star
17

go-redwall

🔥 Dockerized distributed dynamic firewall daemon with Redis backend
Go
8
star
18

Docker-RemoteSyslog2

🐳 Forward server or container logs to remote syslog collectors
Shell
8
star
19

meta-k3s

Shell
7
star
20

stdemuxerhook

🔀 A hook for logrus logger that demuxes logs to stderr and stdout based on severity
Go
6
star
21

datadog-rancher-init

🐶 Sidekick container image for running Datadog Agent in Rancher environments
Python
6
star
22

rancher-v2-logging

6
star
23

habitat-plans

Shell
4
star
24

ansible-k3s-2-node-ha

Ansible playbook for setting up a 2-node, high available k3s cluster using an embedded replicated database
Shell
4
star
25

tiny-operators-catalog

Shell
3
star
26

meta-k3s-odroid-c2

Shell
2
star
27

go-ipintel

👮 Go wrapper for the getipintel.net proxy detection API
Go
2
star
28

fleet-demo

2
star
29

nginx-php55

🐳 Nginx/PHP5.5/NodeJS/Ruby Docker image based on CentOS 7
Shell
1
star
30

k8s-nginx-demo

1
star
31

docker-armhf

🐳 Docker in Docker for ARMv7!
Shell
1
star
32

dotfiles

Shell
1
star
33

docker-selfoss-nginx

🐳 Selfoss - http://selfoss.aditu.de Docker image
PHP
1
star
34

helm-charts

Public Helm chart repository
1
star
35

harvester-rke2-cluster-template

Example RKE2 cluster template for Harvester IaaS
1
star
36

k3s-fleet-demos

1
star
37

ndppd-alpine

Shell
1
star
38

blinken-k8s

Shell
1
star
39

docker-debian-nginx

🐳 Nginx 1.8 (Dotdeb) image based on Debian Wheezy
Shell
1
star
40

docker-debian-s6

🐳 Official debian images pimped with the s6 process supervisor
Shell
1
star
41

rancher-hello-world

Python
1
star