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:
-
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 thebind
line to indicate the location of our TLS certificates. In that directory, we’ve storedsite.pem
.haproxyglobalstats socket :9999 level admin expose-fd listenersfrontend fe_mainmode httpbind :80bind :443 ssl crt /etc/hapee-2.9/certs/haproxyglobalstats socket :9999 level admin expose-fd listenersfrontend fe_mainmode httpbind :80bind :443 ssl crt /etc/hapee-2.9/certs/We update
site.pem
with the new certificate./new_certificate.pem
from the local workstation:nixecho -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 -nixecho -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 - -
Commit the transaction using the Runtime API command commit ssl cert.
nixecho "commit ssl cert /etc/hapee-2.9/certs/site.pem" | \socat tcp-connect:172.25.0.10:9999 -nixecho "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:
-
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 thebind
directive’scrt-list
argument.haproxyfrontend fe_mainmode httpbind :80bind :443 ssl crt-list /etc/hapee-2.9/certificate-list.txthaproxyfrontend fe_mainmode httpbind :80bind :443 ssl crt-list /etc/hapee-2.9/certificate-list.txtWe 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 certificatenixecho -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:9999nixecho -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:9999outputtextInserting certificate '/etc/hapee-2.9/certs/new_certificate.pem' in crt-list '/etc/hapee-2.9/certificate-list.txt'.Success!outputtextInserting 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.
-
Upload the new certificate to the load balancer node.
-
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
- Load balancer configuration file:
-
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 thebind
directive’scrt
argument:haproxyglobalstats socket :9999 level admin expose-fd listenersfrontend fe_mainmode httpbind :80bind :443 ssl crt /certs/haproxyglobalstats socket :9999 level admin expose-fd listenersfrontend fe_mainmode httpbind :80bind :443 ssl crt /certs/Move the new certificate to the certificate directory:
nixsudo mv /home/user/example.pem /certs/site.pemnixsudo mv /home/user/example.pem /certs/site.pem -
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.
-
Reload the load balancer to ensure the old certificate is no longer loaded in memory.
nixsudo systemctl reload hapee-2.9-lbnixsudo 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?