Administration

Manage SSL certificates

There are two ways to manage certificates on a load balancer.

  • Runtime API. The Runtime API provides commands that you can issue directly to the running load balancer. Changes take effect without requiring reload or restart, but if you want changes to persist the next time the load balancer is reloaded or restarted, you have to change files on the load balancer node.
  • Files residing on the load balancer node. These include certificate files, CRT list files, and the load balancer configuration file. This method of managing certificates requires that you reload or restart the load balancer. Changes are persistent. If your application uses a large number of certificates, a restart or reload can have a significanat impact on memory usage.

In practice, you may choose to use both methods: make changes using the Runtime API, and then change the files on the load balancer node to make the changes persistent.

Update an SSL certificate using the Runtime API Jump to heading

You can update an SSL certificate that was loaded into memory at startup. Use the Runtime API command set ssl cert. The workflow to update a certificate is:

  1. Use set ssl cert to start a transaction that replaces the application’s certificate with one that you have on your local workstation.

    In this example, we specify the crt argument on the bind line to indicate the location of our TLS certificates. In that directory, we’ve stored site.pem.

    haproxy
    global
    stats socket :9999 level admin expose-fd listeners
    frontend fe_main
    mode http
    bind :80
    bind :443 ssl crt /etc/hapee-2.9/certs/
    haproxy
    global
    stats socket :9999 level admin expose-fd listeners
    frontend fe_main
    mode http
    bind :80
    bind :443 ssl crt /etc/hapee-2.9/certs/

    We update site.pem with the new certificate ./new_certificate.pem from the local workstation:

    nix
    echo -e "set ssl cert /etc/hapee-2.9/certs/site.pem <<\n$(cat ./new_certificate.pem)\n" | \
    socat tcp-connect:172.25.0.10:9999 -
    nix
    echo -e "set ssl cert /etc/hapee-2.9/certs/site.pem <<\n$(cat ./new_certificate.pem)\n" | \
    socat tcp-connect:172.25.0.10:9999 -
  2. Commit the transaction using the Runtime API command commit ssl cert.

    nix
    echo "commit ssl cert /etc/hapee-2.9/certs/site.pem" | \
    socat tcp-connect:172.25.0.10:9999 -
    nix
    echo "commit ssl cert /etc/hapee-2.9/certs/site.pem" | \
    socat tcp-connect:172.25.0.10:9999 -

When you use the Runtime API, your changes take effect in the memory of the running load balancer, but are not stored on disk. They will therefore be lost when the load balancer stops. To make the changes persistent, modify certificate files on the load balancer node.

Add an SSL certificate to a CRT list using the Runtime API Jump to heading

You can add an SSL certificate to a CRT list using the Runtime API command add ssl crt-list. A CRT list is a text file listing certificates, specified in the load balancer configuration with the bind directive’s crt-list argument.

Important

Adding a new certificate to a CRT list does not add the certificate itself. To add the certificate, call new ssl crt-list, set ssl crt-list, and commit ssl crt-list. Then call add ssl crt-list.

The workflow to add a certificate to a CRT list is:

  1. Use add ssl crt-list to upload the local certificate file into a CRT list in memory.

    In this example, the CRT list, /etc/hapee-2.9/certificate-list.txt, is specified in the bind directive’s crt-list argument.

    haproxy
    frontend fe_main
    mode http
    bind :80
    bind :443 ssl crt-list /etc/hapee-2.9/certificate-list.txt
    haproxy
    frontend fe_main
    mode http
    bind :80
    bind :443 ssl crt-list /etc/hapee-2.9/certificate-list.txt

    We will add a certificate residing on the local workstation, new_certificate.pem, to the load balancer CRT list. The command also sets ALPN attributes and the SNI value for the certificate

    nix
    echo -e "add ssl crt-list /etc/hapee-2.9/certificate-list.txt <<\n/etc/hapee-2.9/certs/new_certificate.pem [alpn h2] mysite.local\n" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    nix
    echo -e "add ssl crt-list /etc/hapee-2.9/certificate-list.txt <<\n/etc/hapee-2.9/certs/new_certificate.pem [alpn h2] mysite.local\n" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    text
    Inserting certificate '/etc/hapee-2.9/certs/new_certificate.pem' in crt-list '/etc/hapee-2.9/certificate-list.txt'.
    Success!
    output
    text
    Inserting certificate '/etc/hapee-2.9/certs/new_certificate.pem' in crt-list '/etc/hapee-2.9/certificate-list.txt'.
    Success!

When you use the Runtime API, your changes take effect in the memory of the running load balancer, but are not stored on disk. They will therefore be lost when the load balancer stops. To make the changes persistent, modify certificate files on the load balancer node.

Modify certificate files on the load balancer node Jump to heading

To make certificate changes persistent, modify certificate files on the load balancer node.

  1. Upload the new certificate to the load balancer node.

  2. On the load balancer node, confirm the location of existing certificates. Suggested places to inspect:

    • Load balancer configuration file: /etc/hapee-2.9/hapee-lb.cfg
    • CRT lists, for example: /etc/hapee-2.9/certificate-list.txt
  3. Move the new certificate to the certificate directory and give it the desired name.

    In this example, the application’s TLS certificate file, site.pem, is located in directory /certs, which is specified by the bind directive’s crt argument:

    haproxy
    global
    stats socket :9999 level admin expose-fd listeners
    frontend fe_main
    mode http
    bind :80
    bind :443 ssl crt /certs/
    haproxy
    global
    stats socket :9999 level admin expose-fd listeners
    frontend fe_main
    mode http
    bind :80
    bind :443 ssl crt /certs/

    Move the new certificate to the certificate directory:

    nix
    sudo mv /home/user/example.pem /certs/site.pem
    nix
    sudo mv /home/user/example.pem /certs/site.pem
  4. If you’re adding a certificate with a new name, edit the load balancer configuration file or CRT list file and make modifications to specify the new certificate.

  5. Reload the load balancer to ensure the old certificate is no longer loaded in memory.

    nix
    sudo systemctl reload hapee-2.9-lb
    nix
    sudo systemctl reload hapee-2.9-lb

See also Jump to heading

Do you have any suggestions on how we can improve the content of this page?