Basics of enabling TLS

Use Transport Layer Security (TLS) to encrypt traffic between the load balancer and clients, and between the load balancer and the backend servers. TLS is the successor to the deprecated Secure Sockets Layer (SSL) protocol. It’s the technology that allows you to serve a website over HTTPS.

Client-side TLS Jump to heading #

In this section, you’ll learn how to configure TLS between clients and the load balancer. Your version determines which configuration directives you should use. This table explains where to go:

Product version	Go to…
HAProxy 3.2 and newer HAProxy Enterprise 3.2r1 and newer HAProxy ALOHA 17.5 and newer	Use crt-store with ssl-f-use
HAProxy 3.0 to 3.1 HAProxy Enterprise 3.0r1 to 3.1 HAProxy ALOHA 16.5 to 17.0	Use crt-store with crt
HAProxy 2.9 and older HAProxy Enterprise 2.9r1 and older HAProxy ALOHA 16.0 and older	Use crt-list or Use crt alone

Use crt-store with ssl-f-use Jump to heading #

Add a crt-store configuration section to define the file system locations of your TLS certificates and keys. Then, in a frontend section, use those files with ssl-f-use directives. This is the modern way to configure TLS, although we cover older ways — using crt and crt-list — on this page too.

The crt-store configuration section separates the declarations of where certificates are stored from their use in a frontend. Its purpose is to provide additional flexibility and ease of use compared to older methods. It was added in HAProxy 3.0 / HAProxy Enterprise 3.0r1 / HAProxy ALOHA 16.5, but it wasn’t until the addition of the ssl-f-use directive in HAProxy 3.2 / HAProxy Enterprise 3.2r1 / HAProxy ALOHA 17.5 that it qualified as a full solution. Prior to that, you could use crt-store with crt.

To load certificates with crt-store and use them in a frontend with the ssl-f-use directive, follow these steps:

1. Define a crt-store section in your load balancer configuration. A crt-store lets you specify the file system locations of X.509 public certificates and private keys. These files should be in PEM format. In this example, we define a crt-store that loads several TLS files.

   haproxy
   crt-store my_tls_files
     # Set parent directories
     crt-base /etc/haproxy/ssl/certs/
     key-base /etc/haproxy/ssl/private/
     # Load a PEM-formatted file that contains the certificate and key
     load crt "foo.pem"
     # Load separate PEM-formatted certificate and key files
     load crt "bar.crt" key "bar.key"
     # Assign an alias to this line
     load crt "baz.pem" alias "baz"

   haproxy
   crt-store my_tls_files
     # Set parent directories
     crt-base /etc/haproxy/ssl/certs/
     key-base /etc/haproxy/ssl/private/
     # Load a PEM-formatted file that contains the certificate and key
     load crt "foo.pem"
     # Load separate PEM-formatted certificate and key files
     load crt "bar.crt" key "bar.key"
     # Assign an alias to this line
     load crt "baz.pem" alias "baz"

   • The crt-store keyword declares a new section with the name my_tls_files. You’ll use that name when using these files.
   • The crt-base directive sets the directory to search for TLS certificate files.
   • The key-base directive sets the directory to search for TLS private key files. An advantage that crt-store has over older ways is that you don’t need to keep keys in the same directory as certificates if you split them out.
   • The load directives set files to load into memory. You can load a certificate and its key as one file using the crt argument, or separately with the crt and key arguments.

2. In your frontend section, add an ssl argument to your bind directive to enable TLS. Add ssl-f-use directives that refer to the files loaded in the crt-store section.

   haproxy
   frontend example
     bind :443 ssl
     ssl-f-use crt "@my_tls_files/foo.pem"
     ssl-f-use crt "@my_tls_files/bar.crt"
     ssl-f-use crt "@my_tls_files/baz"
     default_backend webservers

   haproxy
   frontend example
     bind :443 ssl
     ssl-f-use crt "@my_tls_files/foo.pem"
     ssl-f-use crt "@my_tls_files/bar.crt"
     ssl-f-use crt "@my_tls_files/baz"
     default_backend webservers

   • The bind directive needs only an ssl argument.
   • Each ssl-f-use directive refers to a load line from the crt-store. The load directive’s crt argument acts as a reference key. You can also set an alias, as shown for the last load directive, which uses the alias baz.
   • Since we’ve specified more than one ssl-f-use directive, the load balancer chooses the appropriate certificate for the current request based on Server Name Indication (SNI). This allows you to host multiple websites with different domain names at the same IP address and port. Each request will use the certificate that matches the domain name being requested.

3. Optional: Add additional arguments to your bind directive to set TLS options. The arguments affect all of the loaded certificates. Set any of the arguments explained in the bind options configuration reference. You can also add arguments to your ssl-f-use directives to set TLS options. The arguments can be different for each ssl-f-use line and they override those set on the bind directive for the given certificate. Set any of the arguments explained in the ssl-f-use configuration reference.

   For example, here we add the TLS option for ssl-min-ver on the bind directive. The second ssl-f-use directive overrides it with its own value.

   haproxy
   frontend example
     bind :443 ssl ssl-min-ver TLSv1.2
     ssl-f-use crt "@my_tls_files/foo.pem" 
     ssl-f-use crt "@my_tls_files/bar.crt" ssl-min-ver TLSv1.3
     default_backend webservers

   haproxy
   frontend example
     bind :443 ssl ssl-min-ver TLSv1.2
     ssl-f-use crt "@my_tls_files/foo.pem" 
     ssl-f-use crt "@my_tls_files/bar.crt" ssl-min-ver TLSv1.3
     default_backend webservers

4. Optional: To set a default certificate when SNI doesn’t match any certificate, add the default-crt argument to a bind line in your frontend, specifying the location of one of your certificates.

   haproxy
   frontend example
     bind :443 ssl default-crt "@my_tls_files/foo.pem"
     ssl-f-use crt "@my_tls_files/foo.pem"
     ssl-f-use crt "@my_tls_files/bar.crt"
     default_backend webservers

   haproxy
   frontend example
     bind :443 ssl default-crt "@my_tls_files/foo.pem"
     ssl-f-use crt "@my_tls_files/foo.pem"
     ssl-f-use crt "@my_tls_files/bar.crt"
     default_backend webservers

   If you need to support clients that can accept only RSA certificates, you can specify multiple default-crt directives to set ECDSA and RSA files. Encryption with an ECC certificate uses about 1/8 of the CPU of an RSA certificate of an equivalent cryptographic strength. For an example, see default-crt in the configuration manual.

Use crt-store with crt Jump to heading #

Add a crt-store configuration section to define the file system locations of your TLS certificates and keys. Then, in a frontend section, use those files with the bind directive’s crt argument. You can add multiple crt arguments on a bind line to use multiple certificates from a crt-store.

To use a crt-store with the bind directive’s crt argument:

1. Define a crt-store section in your load balancer configuration. A crt-store lets you specify the file system locations of X.509 public certificates and private keys. These files should be in PEM format. In this example, we define a crt-store that loads several TLS files.

   haproxy
   crt-store my_tls_files
     # Set parent directories
     crt-base /etc/haproxy/ssl/certs/
     key-base /etc/haproxy/ssl/private/
     # Load a PEM-formatted file that contains the certificate and key
     load crt "foo.pem"
     # Load separate PEM-formatted certificate and key files
     load crt "bar.crt" key "bar.key"
     # Assign an alias to this line
     load crt "baz.pem" alias "baz"

   haproxy
   crt-store my_tls_files
     # Set parent directories
     crt-base /etc/haproxy/ssl/certs/
     key-base /etc/haproxy/ssl/private/
     # Load a PEM-formatted file that contains the certificate and key
     load crt "foo.pem"
     # Load separate PEM-formatted certificate and key files
     load crt "bar.crt" key "bar.key"
     # Assign an alias to this line
     load crt "baz.pem" alias "baz"

   • The crt-store keyword declares a new section with the name my_tls_files. You’ll use that name when using these files.
   • The crt-base directive sets the directory to search for TLS certificate files.
   • The key-base directive sets the directory to search for TLS private key files.
   • The load directives set files to load into memory. You can load a certificate and its key as one file using the crt argument, or separately with the crt and key arguments.

2. In your frontend section, add an ssl argument to your bind directive to enable TLS. Also, update your bind directive to add crt arguments that refer to the files loaded in the crt-store section.

   haproxy
   frontend example
     bind :443 ssl crt "@my_tls_files/foo.pem" crt "@my_tls_files/bar.crt" crt "@my_tls_files/baz"
     default_backend webservers

   haproxy
   frontend example
     bind :443 ssl crt "@my_tls_files/foo.pem" crt "@my_tls_files/bar.crt" crt "@my_tls_files/baz"
     default_backend webservers

   • The bind directive sets the ssl argument and one or more crt arguments.
   • Each crt argument refers to a load line from the crt-store. The load directive’s crt argument acts as a reference key. You can also set an alias, as shown for the last load directive, which uses the alias baz.
   • Since we’ve specified more than one crt argument, the load balancer chooses the appropriate certificate for the current request based on Server Name Indication (SNI). This allows you to host multiple websites with different domain names at the same IP address and port. Each request will use the certificate that matches the domain name being requested.

3. Optional: Add additional arguments to your bind directive to set TLS options. The arguments affect all of the loaded certificates. Set any of the arguments explained in the bind options configuration reference.

   For example, here we add the TLS option for ssl-min-ver on the bind directive.

   haproxy
   frontend example
     bind :443 ssl crt "@my_tls_files/foo.pem" ssl-min-ver TLSv1.2
     default_backend webservers

   haproxy
   frontend example
     bind :443 ssl crt "@my_tls_files/foo.pem" ssl-min-ver TLSv1.2
     default_backend webservers

4. Optional: To set a default certificate when SNI doesn’t match any certificate, add the default-crt argument to a bind line in your frontend, specifying the location of one of your certificates. Declare the default-crt argument before any crt arguments or else any preceding crt arguments also become default certificates, since the legacy behavior was to treat the first crt as the default.

   haproxy
   frontend example
     bind :443 ssl default-crt "@my_tls_files/foo.pem" crt "@my_tls_files/foo.pem" crt "@my_tls_files/bar.crt"
     default_backend webservers

   haproxy
   frontend example
     bind :443 ssl default-crt "@my_tls_files/foo.pem" crt "@my_tls_files/foo.pem" crt "@my_tls_files/bar.crt"
     default_backend webservers

   If you need to support clients that can accept only RSA certificates, you can specify multiple default-crt directives to set ECDSA and RSA files. Encryption with an ECC certificate uses about 1/8 of the CPU of an RSA certificate of an equivalent cryptographic strength. For an example, see default-crt in the configuration manual.

Use crt-list Jump to heading #

The modern way to define TLS options per certificate is with the ssl-f-use directive. Before that existed, the way to load multiple certificates and set different TLS options for them was to create a separate text file named a crt-list. A crt-list has a line for each certificate. Each line begins with the path to the PEM-formatted file that contains the certificate and its key. The end of a line can set additional TLS options.

To use a crt-list file:

1. Create a text file. In this example, our file sets the locations for foo.pem and bar.pem. These files contain certificates and their private keys. They are followed by their individual TLS options. You can also refer to certificates defined in a crt-store.

   crt-list.txt
   nix
   /etc/haproxy/ssl/certs/foo.pem [alpn h2 ssl-min-ver TLSv1.2]
   /etc/haproxy/ssl/certs/bar.pem [ssl-min-ver TLSv1.3]
   @my_tls_files/foo.pem [ciphers ECDHE-RSA-AES128-GCM-SHA256]

   crt-list.txt
   nix
   /etc/haproxy/ssl/certs/foo.pem [alpn h2 ssl-min-ver TLSv1.2]
   /etc/haproxy/ssl/certs/bar.pem [ssl-min-ver TLSv1.3]
   @my_tls_files/foo.pem [ciphers ECDHE-RSA-AES128-GCM-SHA256]

2. In your frontend section, add an ssl argument to your bind directive to enable TLS. Also, update your bind directive to use a crt-list argument to refer to the path to the text file. The load balancer will load the certificates according to the options specified in that file.

   haproxy
   frontend example
     bind :443 ssl crt-list /etc/haproxy/ssl/certs/crt-list.txt
     default_backend webservers

   haproxy
   frontend example
     bind :443 ssl crt-list /etc/haproxy/ssl/certs/crt-list.txt
     default_backend webservers

3. Optional: Add additional arguments to your bind directive to set TLS options. The arguments affect all of the loaded certificates. Set any of the arguments explained in the bind options configuration reference. Arguments that you set in the crt-list file will override those set on the bind directive for the given certificate. Set any of the arguments explained in the crt-list configuration reference.

4. Optional: To set a default certificate when SNI doesn’t match any certificate, mark your certificate with an asterisk to indicate that the load balancer should consider it to be the default. For example:

   crt-list.txt
   nix
   /etc/haproxy/ssl/certs/foo.pem [alpn h2 ssl-min-ver TLSv1.2] *
   /etc/haproxy/ssl/certs/bar.pem [ssl-min-ver TLSv1.3]

   crt-list.txt
   nix
   /etc/haproxy/ssl/certs/foo.pem [alpn h2 ssl-min-ver TLSv1.2] *
   /etc/haproxy/ssl/certs/bar.pem [ssl-min-ver TLSv1.3]

Use crt alone Jump to heading #

You can load TLS files without defining a crt-store section. Set one or more crt arguments on a bind directive in a frontend section to load certificate files into memory. These files should be in PEM format. A crt can be the path to a file that contains a certificate and its key or it can be the path to a directory of files.

To use the bind directive’s crt argument:

1. In your frontend section, add an ssl argument to your bind directive to enable TLS. Also, update your bind directive to add one or more crt arguments to set files to load into memory.

   haproxy
   frontend example
     bind :443 ssl crt /etc/haproxy/ssl/certs/foo.pem
     default_backend webservers

   haproxy
   frontend example
     bind :443 ssl crt /etc/haproxy/ssl/certs/foo.pem
     default_backend webservers

   • The ssl argument enables TLS encryption.
   • The crt argument indicates the file path to a .pem file that contains both your server’s PEM-formatted TLS certificate and its private key. You will typically need to concatenate these two things manually into a single file. Simply copy and paste them into the file.

   You can also set the crt argument to a directory of TLS files. The load balancer will use Server Name Indication (SNI) to search the directory for a certificate that has a Common Name (CN) or Subject Alternative Name (SAN) field that matches the requested domain, which the client sends during the TLS handshake. This allows you to host multiple websites with different domain names at the same IP address and port. Each request will use the certificate that matches the domain name being requested. In the example below, we set crt to a directory that contains TLS certificates:

   haproxy
   frontend example
     bind :443 ssl crt /etc/haproxy/ssl/certs
     default_backend webservers

   haproxy
   frontend example
     bind :443 ssl crt /etc/haproxy/ssl/certs
     default_backend webservers

   If SNI doesn’t match any certificate, the load balancer will use the first certificate in the directory. If you intend to load default certificates in this way, ensure that this first file is a multi-cert bundle (contains a certificate and key).

2. Optional: Add additional arguments to your bind directive to set TLS options. The arguments affect all of the loaded certificates. Set any of the arguments explained in the bind options configuration reference.

   For example, here we add the argument ssl-min-ver on the bind directive.

   haproxy
   frontend example
     bind :443 ssl crt /etc/haproxy/ssl/certs/foo.pem ssl-min-ver TLSv1.2
     default_backend webservers

   haproxy
   frontend example
     bind :443 ssl crt /etc/haproxy/ssl/certs/foo.pem ssl-min-ver TLSv1.2
     default_backend webservers

Redirect HTTP to HTTPS Jump to heading #

To enable an HTTP to HTTPS redirect, use the http-request redirect scheme directive:

haproxy
frontend example
  mode http
  bind :80
  bind :443 ssl
  ssl-f-use crt "@my_tls_files/foo.pem"
  http-request redirect scheme https unless { ssl_fc }
  default_backend webservers

haproxy
frontend example
  mode http
  bind :80
  bind :443 ssl
  ssl-f-use crt "@my_tls_files/foo.pem"
  http-request redirect scheme https unless { ssl_fc }
  default_backend webservers

In this example:

• We set mode to http.
• We enable TLS with the ssl argument on a bind line. Notice that this frontend listens on both ports 80 for HTTP and 443 for HTTPS. Traffic received at HTTP port 80 will be redirected to HTTPS port 443.
• The http-request redirect scheme directive redirects HTTP traffic to the HTTPS scheme, unless it’s already HTTPS as indicated by the ssl_fc condition.

HTTP Strict Transport Security Jump to heading #

Use HTTP Strict Transport Security (HSTS) to prevent a man-in-the-middle attack, which can happen if a client’s initial request is sent over cleartext HTTP, even if they are then redirected to HTTPS. An attacker could intercept their initial request and from then on eavesdrop on the session. The HSTS policy caches your website’s domain in the browser’s list of sites that should initiate communication over HTTPS from the start. Then, no redirect from HTTP to HTTPS is required. This policy can prevent man-in-the-middle attacks, where redirected traffic is intercepted by a malicious party.

HSTS works by sending the response header Strict-Transport-Security to clients. This header instructs the client’s browser to use HTTPS instead of HTTP for this domain and, optionally, its subdomains.

The Strict-Transport-Security header fields are:

Field	Description
max-age	Required. Sets how long the browser should remember the rule, in seconds, after the client has visited the website at least once. The next time the client accesses your domain, the HSTS policy will be cached again.
includeSubDomains	Tells the browser that it should include all of your subdomains in the rule.
preload	Submit your site to the HSTS preload service, which is a registry of websites that browsers will connect to using HTTPS automatically. The preload option requires includeSubDomains.

To enable HSTS:

1. Configure the redirect to HTTPS action in your frontend section.

2. Insert the Strict-Transport-Security header into every response using the http-response set-header directive.

   With this configuration, HAProxy returns the Strict-Transport-Security header, which instructs the browser to route messages to this website using HTTPS from the start. This rule lasts for 16,000,000 seconds (approximately six months) after the client has visited your website at least once. From then on, attackers will no longer get a chance to intercept a client’s messages. As a side effect, by not needing a redirect to HTTPS, it also avoids one round trip between the client and server, improving response times.

   Testing with max-age

   During testing, use a low max-age value, such as 600 seconds. If you’ve set includeSubDomains, you may find during testing that some subdomains aren’t configured to accept traffic over HTTPS. Give yourself time to find those issues without a long max-age value. You can also set max-age=0 to disable HSTS.

   haproxy
   frontend example
     bind :80
     bind :443 ssl
     ssl-f-use crt "@my_tls_files/foo.pem"
     http-request redirect scheme https code 301 unless { ssl_fc }
     # max-age is mandatory. 16000000 seconds is approximately 6 months. Use a low value during testing.
     http-response set-header Strict-Transport-Security "max-age=16000000; includeSubDomains; preload;"
     default_backend webservers

   haproxy
   frontend example
     bind :80
     bind :443 ssl
     ssl-f-use crt "@my_tls_files/foo.pem"
     http-request redirect scheme https code 301 unless { ssl_fc }
     # max-age is mandatory. 16000000 seconds is approximately 6 months. Use a low value during testing.
     http-response set-header Strict-Transport-Security "max-age=16000000; includeSubDomains; preload;"
     default_backend webservers

Generate dummy certificates Jump to heading #

If you don’t have a TLS certificate that you can use for testing, you can have HAProxy generate a self-signed certificate for you. The certificate is a 24-hour expired certificate. The dummy certificate exists only in process memory and doesn’t persist if the process restarts.

To create a dummy TLS certificate, use the following arguments on a load directive in a crt-store section:

• generate-dummy: Generate a self-signed certificate and private key. One of on or off. Default: off.
• keytype: Set the type of key, either RSA or ECDSA. Default: RSA.
• bits: Set the number of bits for generating an RSA certificate. Default: 2048.
• curves: Set the elliptic curve for generating an ECDSA certificate. Default: P-384.

In this example, we generate a self-signed 2048-bit RSA certificate named dummycert.pem.rsa and use it in a frontend bind directive:

haproxy
crt-store mycertificates
  load generate-dummy on keytype RSA bits 2048 crt "dummycert.pem.rsa"
frontend myfrontend1 from unnamed_defaults_1
  ...
  bind *:443 name *:443 ssl crt "@mycertificates/dummycert.pem.rsa"

haproxy
crt-store mycertificates
  load generate-dummy on keytype RSA bits 2048 crt "dummycert.pem.rsa"
frontend myfrontend1 from unnamed_defaults_1
  ...
  bind *:443 name *:443 ssl crt "@mycertificates/dummycert.pem.rsa"

Use the HAProxy Runtime API show ssl cert command to list details about the dummy certificate:

nix
echo "show ssl cert @mycertificates/dummycert.pem.rsa" | socat stdio tcp4-connect:127.0.0.1:9999

nix
echo "show ssl cert @mycertificates/dummycert.pem.rsa" | socat stdio tcp4-connect:127.0.0.1:9999

output
text
Filename: @mycertificates/dummycert.pem.rsa
Crt filename: dummycert.pem.rsa
Option: ocsp-update off
Option: jwt off
Status: Used
Serial:
notBefore: Jun 14 19:04:16 2026 GMT
notAfter: Jun 15 19:04:16 2026 GMT
Subject Alternative Name:
Algorithm: RSA2048
SHA1 FingerPrint: C114A461E74FB78CF8036258A4A4387AD95B1856
Subject: /CN=expired
Issuer: /CN=expired
OCSP Response Key:

output
text
Filename: @mycertificates/dummycert.pem.rsa
Crt filename: dummycert.pem.rsa
Option: ocsp-update off
Option: jwt off
Status: Used
Serial:
notBefore: Jun 14 19:04:16 2026 GMT
notAfter: Jun 15 19:04:16 2026 GMT
Subject Alternative Name:
Algorithm: RSA2048
SHA1 FingerPrint: C114A461E74FB78CF8036258A4A4387AD95B1856
Subject: /CN=expired
Issuer: /CN=expired
OCSP Response Key:

Server-side TLS Jump to heading #

You can encrypt traffic between the load balancer and backend servers. TLS is the successor to the deprecated Secure Sockets Layer (SSL).

To configure TLS between the load balancer and your backend servers, add the ssl and verify arguments to your server lines in a backend:

haproxy
backend webservers
  mode http
  balance roundrobin
  server web1 10.0.0.5:443 ssl verify required ca-file /myca.pem
  server web2 10.0.0.6:443 ssl verify required ca-file /myca.pem

haproxy
backend webservers
  mode http
  balance roundrobin
  server web1 10.0.0.5:443 ssl verify required ca-file /myca.pem
  server web2 10.0.0.6:443 ssl verify required ca-file /myca.pem

In this example:

• The ssl argument enables TLS to the server.
• The verify argument indicates whether to verify that the server’s TLS certificate was signed by a trusted Certificate Authority (CA).
• The ca-file argument sets the CA for validating the server’s certificate.

Typically, you will use port 443, which signifies the HTTPS protocol, when connecting to servers over TLS.

About the verify argument

Setting verify to required configures the load balancer to check the server’s certificate against a Certificate Authority (CA) certificate, which you specify with the ca-file argument. You can also set ca-file to @system-ca, in which case it will refer to the trusted CAs from your operating system.

You can also set verify to none, which means don’t check that the server’s certificate is trusted. This is helpful when the server uses a self-signed certificate.

You can also include a crl-file parameter to indicate a certificate revocation list.

When mode is set to http, you can send an SNI value to your backend servers. Add the sni argument followed by a fetch method that returns the name you wish to use. Often, you will use the req.hdr fetch to get the Host header value, as shown below:

haproxy
backend webservers
  server web1 10.0.0.5:443 ssl verify required ca-file /myca.pem  sni req.hdr(Host)
  server web2 10.0.0.6:443 ssl verify required ca-file /myca.pem  sni req.hdr(Host)

haproxy
backend webservers
  server web1 10.0.0.5:443 ssl verify required ca-file /myca.pem  sni req.hdr(Host)
  server web2 10.0.0.6:443 ssl verify required ca-file /myca.pem  sni req.hdr(Host)

See also Jump to heading #

• To enable SSL deciphering, see ssl.
• To specify a PEM file for a bind, or the directory containing the certificate and associated private keys, see crt.
• To specify a file containing a list of certificates and their TLS options, see crt-list.
• For enhanced flexibility in managing certificates, see crt-store.
• To perform redirects such as redirecting HTTP requests to HTTPS, see http-request redirect.
• To set the default behavior for SSL verification on the server side, see ssl-server-verify.
• When you have enabled TLS between the load balancer and backend servers, you can specify a PEM file containing a CA certificate for validating the server certificate, see ca-file reference.
• To specify whether the server certificate should be verified, see verify reference.
• To list details about a TLS certificate, see show ssl cert.
• See the load reference for options available for the load directive.