HAProxy Enterprise Documentation 1.7r1


HAProxy Enterprise supports Transport Layer Security (TLS) for encrypting traffic between itself and clients. You have the option of using or not using TLS between HAProxy Enterprise and your backend servers, if you require end-to-end encryption.

Enable TLS to clients

To configure TLS between the load balancer and clients, you must:

  • add the ssl parameter to a bind line in a frontend section;

  • add the crt parameter that points to a .pem file that contains your PEM formatted TLS certificate and key.

Typically, you will use port 443, which signifies the HTTPS protocol:

frontend www
   bind :443 ssl crt /etc/hapee-1.7/certs/site.pem
   default_backend webservers

You can also specify a directory for the crt parameter. By using Server Name Indication (SNI), HAProxy Enterprise will 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 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:

frontend www
   bind :443 ssl crt /etc/hapee-1.7/certs
   default_backend webservers

Redirect HTTP to HTTPS

When you've set mode to http in your frontend, you can enable an HTTP to HTTPS redirect. Use the http-request redirect directive, as shown below. Notice that this frontend listens on both ports 80 for HTTP and 443 for HTTPS:

frontend www
   bind :80
   bind :443 ssl crt /etc/hapee-1.7/certs
   http-request redirect scheme https unless { ssl_fc }
   default_backend webservers

Enable TLS to servers

To configure TLS between the load balancer and your backend servers, you must:

  • add the ssl parameter to the server lines in a backend section;

  • add the verify parameter to indicate whether to verify that the server's TLS certificate is trusted.

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

backend webservers
   server web1 ssl verify none
   server web2 ssl verify none

In this example, verify is set to none, which means that HAProxy Enterprise will not check that the server's certificate is trusted. This is helpful when using self-signed certificates.

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 parameter, as shown below:

backend webservers
   server web1 ssl verify required ca-file /etc/hapee-1.7/myca.pem
   server web2 ssl verify required ca-file /etc/hapee-1.7/myca.pem

When mode is set to http, you can send an SNI value to your backend servers. Add the sni parameter followed by a fetch 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:

backend webservers
   server web1 ssl verify required ca-file /etc/hapee-1.7/myca.pem  sni req.hdr(Host)
   server web2 ssl verify required ca-file /etc/hapee-1.7/myca.pem  sni req.hdr(Host)

Global settings

Some TLS settings should apply to your entire load balancer, such as whether to allow older versions of TLS or whether to set a list of preferred ciphers. Although there's often a parameter to set these things at the bind or server level, you will often want to apply them across the board. In that case, you can add them to the global section of your configuration.

The following example uses ssl-min-ver to allow only version TLS 1.2 or newer on all bind lines:

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

Use the ssl-default-bind-ciphers directive to set a list of TLS ciphers for bind lines, in order of preference:


Disable validation of server certificates, such as when using self-signed certificates, by setting the ssl-server-verify directive to none:

   ssl-server-verify none

More settings exist. Check the reference guide for details.

Performance Considerations

Consider these factors when estimating TLS encryption performance:

  • Encryption with an ECC certificate uses about 1/8 of the CPU of an RSA certificate of an equivalent cryptographic strength.

    If you have both an ECC and RSA certificate, you can use both at the same time by using the file name extensions. Name the RSA certificate file with an .rsa* extension, such as **example.pem.rsa. Name the ECC certificate with an .ecdsa extension, such as example.pem.ecdsa. In your configuration, set the crt parameter to load the file with only the .crt extension, such as crt example.pem.

  • How large are your RSA keys? 2048 is typical, 4096 will be substantially slower. The older 1024 is considered insecure and will no longer be signed by public CAs.

  • Are TLS session tickets enabled on the HAProxy Enterprise server? This can increase the speed of the TLS handshake.

The following rules of thumb will help you decide how many cores you need to assign to HAProxy Enterprise:

  • A 3.7ghz CPU core will take about 1ms to process a 2048 bit key exchange, meaning you can do 1000 key exchanges per second.

  • 1 GB of RAM can support 8000 open TLS connections.

If you decide that your use case will likely require more than one core, you can use the cpu-map options with nbthread to pin threads to specific cores.

For example:

   nbthread 4
   cpu-map auto:1/1-4 0-3

Next up