Operating System Ubuntu

How to Add SSL/TLS Termination to HAProxy on Ubuntu 24.04

Add an HTTPS frontend to HAProxy on Ubuntu 24.04 with a combined PEM certificate, an HTTP-to-HTTPS redirect, a minimum TLS version and the headers backends need.

SSL termination (today really TLS termination) means HAProxy accepts HTTPS connections from visitors, decrypts them, and passes plain HTTP to your backend servers. The certificate lives in one place and the backends need no changes. This guide adds an HTTPS frontend to an existing HAProxy setup on Ubuntu 24.04, which ships HAProxy 2.8; the same configuration works on Ubuntu 22.04 and Debian 12.

Ubuntu 14.04 and HAProxy 1.5, which older versions of this guide used, are end-of-life. If you are upgrading from such a setup, note that the reqadd and rspadd directives were removed in HAProxy 2.1 and stop the service from starting; the replacements are shown below.

Requirements

  • HAProxy installed and already balancing plain HTTP to a working backend. The examples call the backend www-backend.
  • A user that can run sudo.
  • Port 443 open in your firewall.
  • A certificate. For a public site, use one from a certificate authority. For testing or internal use, the self-signed certificate created below is enough.

If HAProxy is not installed yet:

sudo apt update
sudo apt install haproxy

Create the certificate file

HAProxy expects the certificate and its private key together in one PEM file. Create a directory that only root can read:

sudo mkdir -p /etc/haproxy/certs
sudo chmod 700 /etc/haproxy/certs

Option 1: self-signed certificate

Generate a key and a certificate valid for one year in a single command. Replace example.com with the name you will use to reach the load balancer:

sudo openssl req -x509 -newkey rsa:2048 -noenc -days 365 \
  -keyout /etc/haproxy/certs/example.com.key \
  -out /etc/haproxy/certs/example.com.crt \
  -subj "/CN=example.com" \
  -addext "subjectAltName=DNS:example.com,DNS:www.example.com"

Combine both parts into the file HAProxy will load and restrict access to it:

sudo sh -c 'cat /etc/haproxy/certs/example.com.crt /etc/haproxy/certs/example.com.key > /etc/haproxy/certs/example.com.pem'
sudo chmod 600 /etc/haproxy/certs/example.com.pem

Browsers will show a warning for a self-signed certificate because no trusted authority issued it. The connection is still encrypted.

Option 2: certificate from a certificate authority

Concatenate the certificate, any intermediate certificates and the private key into one file in the same way. With a Let's Encrypt certificate that means joining fullchain.pem and privkey.pem:

sudo sh -c 'cat /etc/letsencrypt/live/example.com/fullchain.pem /etc/letsencrypt/live/example.com/privkey.pem > /etc/haproxy/certs/example.com.pem'
sudo chmod 600 /etc/haproxy/certs/example.com.pem

Repeat this step and reload HAProxy every time the certificate is renewed.

Configure HAProxy

Open the configuration file:

sudo nano /etc/haproxy/haproxy.cfg

Set a minimum TLS version

SSLv3, TLS 1.0 and TLS 1.1 are obsolete. In the global section, make sure this line is present so that every bind line accepts TLS 1.2 or newer only. If the section already has an ssl-default-bind-options line, edit it instead of adding a second one:

global
    ssl-default-bind-options ssl-min-ver TLSv1.2

Add the HTTPS listener

Extend your existing HTTP frontend so that it listens on both ports. If your frontend has a different name, keep it and add the new lines:

frontend web
    mode http
    bind :80
    bind :443 ssl crt /etc/haproxy/certs/example.com.pem alpn h2,http/1.1

    http-request redirect scheme https unless { ssl_fc }
    http-request set-header X-Forwarded-Proto https if { ssl_fc }
    http-response set-header Strict-Transport-Security "max-age=600"

    default_backend www-backend

What each line does:

  • bind :443 ssl crt … listens on port 443 on all addresses, enables TLS and loads the PEM file. To listen on one address only, write it before the colon, for example bind 203.0.113.10:443.
  • alpn h2,http/1.1 offers HTTP/2 to clients that support it and HTTP/1.1 to the rest.
  • http-request redirect scheme https unless { ssl_fc } sends visitors who arrive over plain HTTP to the HTTPS address. ssl_fc is true when the client connection used TLS.
  • http-request set-header X-Forwarded-Proto https tells the backend application that the original request was HTTPS, so it generates correct links and does not redirect in a loop. This replaces the old reqadd X-Forwarded-Proto:\ https.
  • http-response set-header Strict-Transport-Security … adds the HSTS header, which tells browsers to use HTTPS for this host from now on. It replaces the old rspadd line. Start with a short max-age such as 600 seconds, and raise it (31536000 is one year) only when HTTPS works for everything on the domain. Leave this line out while you test with a self-signed certificate.

The backend section needs no changes: HAProxy keeps talking plain HTTP to the servers listed there.

backend www-backend
    mode http
    balance roundrobin
    option forwardfor
    server web1 198.51.100.11:80 check
    server web2 198.51.100.12:80 check

More than one domain

Point crt at the directory instead of a single file and put one PEM file per site in it. HAProxy picks the certificate that matches the host name the client asks for (SNI) and uses the first file when nothing matches:

bind :443 ssl crt /etc/haproxy/certs/ alpn h2,http/1.1

In that case keep only the combined .pem files in the directory and store the separate .crt and .key files elsewhere.

Check the configuration and reload

Validate the file before applying it. A typo here would otherwise take the load balancer down:

sudo haproxy -c -f /etc/haproxy/haproxy.cfg

When the check passes, reload the service:

sudo systemctl reload haproxy

Verify HTTPS

Request the site over HTTPS. The -k option is only needed for a self-signed certificate:

curl -kI https://example.com/

Confirm that plain HTTP is redirected:

curl -I http://example.com/

The second command should return a 302 status with a location: https://example.com/ header. To look at the certificate and the negotiated protocol version:

openssl s_client -connect example.com:443 -servername example.com </dev/null

If something fails, read the service log:

sudo journalctl -u haproxy --no-pager -n 50

Frequently asked questions

Is the traffic between HAProxy and the backends encrypted?

No. With termination, that leg is plain HTTP, which is fine on a private network you control. If the backends are reached over an untrusted network, add ssl verify required ca-file … to the server lines to re-encrypt, or use TCP mode and let the backends handle TLS themselves.

My application redirects endlessly after enabling HTTPS. Why?

The application sees a plain HTTP request from HAProxy and tries to force HTTPS itself. Make sure the X-Forwarded-Proto header is set as shown and that the application or its web server is configured to trust that header from the load balancer's address.

Should the redirect return 301 instead of 302?

The default is a temporary redirect, which is the safer choice while you test. Once everything works you can make it permanent with http-request redirect scheme https code 301 unless { ssl_fc }.

Do I have to restart HAProxy when the certificate changes?

A reload is enough. systemctl reload haproxy starts new worker processes with the new file while existing connections finish on the old ones.

Share story:

Continue reading other guides on How VPS.