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-3.0/certs/

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

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

   nix
   echo -e "set ssl cert /etc/hapee-3.0/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-3.0/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-3.0/certs/site.pem" | \
   socat tcp-connect:172.25.0.10:9999 -

   nix
   echo "commit ssl cert /etc/hapee-3.0/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.

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-3.0/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-3.0/certificate-list.txt

   haproxy
   frontend fe_main
     mode http
     bind :80
     bind :443 ssl crt-list /etc/hapee-3.0/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-3.0/certificate-list.txt <<\n/etc/hapee-3.0/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-3.0/certificate-list.txt <<\n/etc/hapee-3.0/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-3.0/certs/new_certificate.pem' in crt-list '/etc/hapee-3.0/certificate-list.txt'.
   Success! 

   output
   text
   Inserting certificate '/etc/hapee-3.0/certs/new_certificate.pem' in crt-list '/etc/hapee-3.0/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-3.0/hapee-lb.cfg
   • CRT lists, for example: /etc/hapee-3.0/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-3.0-lb

   nix
   sudo systemctl reload hapee-3.0-lb

See also Jump to heading #

• add ssl crt-list
• commit ssl cert
• set ssl cert