Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time
May 15, 2018 14:27
May 15, 2018 14:27
May 15, 2018 14:27

HAProxy ACME v2 client

Important notice

Beware, the fixes to support for ACME v2 protocol were recently merged, there might be some sharp edges but it should work.

This is a client implementation for ACME (Automatic Certificate Management Environment) protocol, currently draft IETF standard (

The protocol will be supported by Let's Encrypt project from March 2018. and it is expected that other Certificate Authorities will support this ACME version in the future.


The main idea of this ACME client is to implement as much functionality inside HAProxy. In addition to supporting single instance HAProxy installations, we also aim to support multi-instance deployments (i.e. you have a cluster of load balancers on which you want to use ACME issued certs).

By using the internal HTTP interface (and http client such as curl), you will be able to execute the following:

  • Upload your own account and domain keys (only RSA keys for now)
  • Automatically register your account on ACME servers (linked to your account key)
  • Request and receive certificates for your domains

The only thing you need to do on your own is to save the received certificate bundles and reload HAProxy.


  • A modern HAProxy version (v1.8) with Lua support (check with haproxy -vv | grep USE_LUA=1)
  • haproxy-lua-http - Lua HTTP server/client for HAProxy Lua host
  • json.lua - Lua JSON library
  • luaossl - OpenSSL bindings for Lua


Install the required Lua libraries to proper LUA_PATH location, and configure haproxy as follows:

    log /dev/log local0 debug
    nbproc 1
    lua-load config.lua
    lua-load acme.lua

    log global
    mode http
    option httplog
    timeout connect 5s
    timeout client 10s
    timeout server 10s

listen http
    bind *:80
    http-request use-service lua.acme if { path_beg /.well-known/acme-challenge/  }

listen acme
    http-request use-service lua.acme

listen acme-ca
  server ca ssl verify required ca-file letsencrypt-x3-ca-chain.pem
  http-request set-header Host

letsencrypt-x3-ca-chain.pem is the concatenation of the active root certificate and intermediate certificate in one pem file, available here :

Configuration is kept in a separate Lua file, where you must explicitly set termsOfServiceAgreed option to true in order to be able to acquire certs. Before doing that, please read latest Let's Encrypt terms of service and subscriber agreement available at

config = {
    registration = {
        -- You can read TOS here:
        termsOfServiceAgreed = false,
        contact = {""}

    -- ACME certificate authority configuration
    ca = {
        -- HAProxy backend/server which proxies requests to ACME server
        proxy_uri = "",
        -- ACME server URI (also returned by ACME directory listings)
        -- Use this server name in HAProxy config
        uri = "",

Key creation

Although Lua module is able to create account key or domain automatically, for performance and security reasons we require that you create your keys separately.

Currently, we only support RSA keys. For account key, key size should be 4096bits, and for domain key 2048bits (minimal key sizes are also enforced by Let's Encrypt).

You can use the following commands to create keys. Note that you need a modern openssl version, we don't use openssl genrsa but openssl genpkey, as we're going to use the same command to create ECDSA keys in the future.

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096 -out account.key
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out


After you have provisioned your keys, you can run certificate order via HTTP. For example by using curl to POST data in multipart/form-data format:

curl -XPOST -F 'account_key=@account.key' \
     -F '' -F '' \
     -F ',,' \

Aliases are optional, and we use curl @ syntax to post files. The output is full certificate chain (with key appended), suitable for direct consumption by HAProxy.


No description, website, or topics provided.







No releases published


No packages published