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 haproxyCreate 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/certsOption 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.pemBrowsers 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.pemRepeat this step and reload HAProxy every time the certificate is renewed.
Configure HAProxy
Open the configuration file:
sudo nano /etc/haproxy/haproxy.cfgSet 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.2Add 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-backendWhat 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 examplebind 203.0.113.10:443.alpn h2,http/1.1offers 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_fcis true when the client connection used TLS.http-request set-header X-Forwarded-Proto httpstells the backend application that the original request was HTTPS, so it generates correct links and does not redirect in a loop. This replaces the oldreqadd 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 oldrspaddline. Start with a shortmax-agesuch 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 checkMore 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.1In 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.cfgWhen the check passes, reload the service:
sudo systemctl reload haproxyVerify 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/nullIf something fails, read the service log:
sudo journalctl -u haproxy --no-pager -n 50Frequently 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.