How to change Certificate on HAProxy

Learn how to manually replace an HAProxy PEM certificate bundle, validate configuration, hot-update it through the Runtime API or reload safely, and verify SNI.

HAProxy commonly loads a single PEM bundle containing the leaf certificate, intermediate certificates, and private key. It can activate a replacement either with a process reload or, when configured, a transactional Runtime API update.

Before you begin

Find the exact bind ... ssl crt path and whether it names one file or a certificate directory. Record Runtime API socket permissions, current workers, and reload method. Build the bundle in the order leaf, intermediates, private key and protect it as key material.

Step-by-step certificate replacement

Create and verify the bundle:

cat leaf.pem intermediates.pem private.key > site.pem
chmod 0600 site.pem
haproxy -c -f /etc/haproxy/haproxy.cfg

For a normal file replacement, install it atomically, validate again, then reload:

install -m 0600 site.pem /etc/haproxy/certs/site.pem.new
mv /etc/haproxy/certs/site.pem.new /etc/haproxy/certs/site.pem
haproxy -c -f /etc/haproxy/haproxy.cfg
systemctl reload haproxy

Where the Runtime API is explicitly enabled and secured, update the already-loaded path transactionally:
```
set ssl cert /etc/haproxy/certs/site.pem <<
<complete PEM bundle>

commit ssl cert /etc/haproxy/certs/site.pem
```
Send the commands through the configured administration socket using an approved client such as socat. Confirm the transaction response. The runtime update avoids replacing workers, but also update the file on disk so a future restart keeps the certificate.

Product-specific considerations

A graceful process reload preserves established connections while new workers accept new handshakes. Runtime API access is privileged because it changes live TLS identity; restrict the socket. For a certificate directory, verify the filename/SNI selection and any .list mapping. Update HA peers independently unless configuration management copies files between them.

Verify the new certificate

openssl s_client -connect lb.example.com:443 -servername app.example.com -showcerts </dev/null
systemctl status haproxy

Query show ssl cert /etc/haproxy/certs/site.pem through the Runtime API when used.

Rollback

Restore the old on-disk bundle and reload, or run another Runtime API transaction with the old complete bundle. Keep disk and runtime state consistent.

Common problems

Bundle omits the private key or uses the wrong order.
Runtime is updated but disk is not, so the next restart reverts.
HAProxy reads another certificate selected by SNI mapping.
Reload command starts no new healthy worker.

Automating certificate replacement with aethercert

The aethercert HAProxy target builds the combined PEM bundle. It can use set ssl cert and commit ssl cert through a Runtime API socket for a live update, or fall back to the configured reload command.

See Deploy targets for the fields this preset takes, what it needs on the host, and how far it has been verified.