HAProxy Enterprise Documentation 2.3r1

add ssl crt-list

Add an entry to an SSL CRT list.


CRT lists are text files that describe the SSL certificates used in your HAProxy Enterprise configuration. In addition to listing the path to the actual certificate, these files can optionally include metadata related to cipher suite support, as well as SNI matching and exclusion patterns.

An example CRT list, stored at /etc/hapee-2.3/certificate-list.txt follows:

/etc/hapee-2.3/certs/test.local.pem [alpn h2 ssl-min-ver TLSv1.2] test.local

The first line lists a certificate, whereas the second line lists a certificate, cipher suite parameters, and the SNI, which lists a single domain explicitly. Note that the SNI filter supports wildcard filters and negation filters such as *.domain.tld and !secure.domain.tld.

Changes to the certificates and crt-list made using the Runtime API are in memory only and not written to disk. They will therefore be lost if you restart HAProxy Enterprise.


In this example, we add the line /etc/hapee-2.3/certs/new_certificate.pem [alpn h2] mysite.local to the CRT list at /etc/hapee-2.3/certificate-list.txt.

Note the syntax for setting the extra ALPN attributes and SNI value.

$ echo -e "add ssl crt-list /etc/hapee-2.3/certificate-list.txt <<\n/etc/haprohaproxy/certs/new_certificate.pem [alpn h2] mysite.local\n" | socat tcp-connect: -
Inserting certificate '/etc/hapee-2.3/certs/new_certificate.pem' in crt-list '/etc/hapee-2.3/certificate-list.txt'.

Contextual Example

This operation will generally be performed as part of a series of transactions. An example is outlined below. This example demonstrates how to upload a new certificate, attach it to HAProxy Enterprise's running configuration, and store it in a CRT list with cipher and SNI parameters. An optional delete command is included at the end.

  1. Add a CRT list to your HAproxy Enterprise configuration file on a bind line:

    frontend fe_main
       mode http
       bind :80
       bind :443 ssl crt-list /etc/hapee-2.3/certificate-list.txt ## This file must exist and contain at least one certificate, self-signed, if need be.
       http-request redirect scheme https unless { ssl_fc }
       default_backend servers
  2. Use the new ssl cert command to create an empty slot for a certificate in HAProxy's memory

    $ echo -e "new  ssl cert /etc/hapee-2.3/certs/new_certificate.pem" | socat tcp-connect: -
    New empty certificate store '/etc/hapee-2.3/certs/new_certificate.pem'!
  3. Begin a transaction to upload the certificate into that slot by using the set ssl cert command.

    The new certificate should be in your local working directory.

    $ echo -e "set ssl cert /etc/hapee-2.3/certs/new_certificate.pem <<\n$(cat ./new_certificate.pem)\n" | socat tcp-connect: -
    Transaction created for certificate /etc/hapee-2.3/certs/new_certificate.pem!
  4. Commit the transaction:

    $ echo -e "commit ssl cert /etc/hapee-2.3/certs/new_certificate.pem" | socat tcp-connect: -
    Committing /etc/hapee-2.3/certs/new_certificate.pem
  5. Add a line to the CRT list, to add the certificate, cipher suite and SNI options:

    $ echo -e "add ssl crt-list /etc/hapee-2.3/certificate-list.txt <<\n/etc//haproxy/certs/new_certificate.pem [alpn h2] mysite.local\n" | socat tcp-connect: -
    Inserting certificate '/etc/hapee-2.3/certs/new_certificate.pem' in crt-list '/etc//haproxy/certificate-list.txt'.
  6. Use show ssl crt-list to verify that the CRT list was updated correctly:

    $ echo "show ssl crt-list /etc/hapee-2.3/certificate-list.txt" | socat tcp-connect: -# /etc//haproxy/certificate-list.txt
    /etc/hapee-2.3/certs/test.local.pem [alpn h2 ssl-min-ver TLSv1.2] test.local
    /etc/hapee-2.3/certs/new_certificate.pem [alpn h2] mysite.local
  7. Use del ssl crt-list to delete an entry from the CRT list:

    $ echo -e "del ssl crt-list /etc/hapee-2.3/new_certificate.pem" | socat tcp-connect: -
    Entry '/etc/hapee-2.3/new_certificate.pem' deleted in crtlist '/etc/hapee-2.3/certificate-list.txt'!

See also

Next up

clear acl