Tutorials

Manage SSL/TLS certificates

On this page

You can manage SSL/TLS certificates programmatically by calling the API endpoint /services/haproxy/storage/ssl_certificates.

Getting and setting the version parameter Jump to heading

When making a POST, PUT, or DELETE API call, you must add the version URL parameter. For example:

nix
http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=1
nix
http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=1

The version parameter must match the load balancer’s current configuration version. This is because the Data Plane API uses optimistic concurrency control, or optimistic locking, to manage its transactions. This ensures that if multiple entities modify a resource that the changes are applied correctly. The APIv3 examples in this section make a GET request to /v3/services/haproxy/configuration/version immediately before making a call to update a resource to retrieve the version and populate the CFGVER environment variable for the URL version parameter as is shown in the following command:

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)

You will then use the value of the environment variable to populate the version parameter in the endpoint URL. An example URL may look like this. Note the environment variable reference, $CFGVER:

nix
http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=$CFGVER
nix
http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=$CFGVER

List certifiates Jump to heading

To get a list of all certificates on disk, make a GET request to the ssl_certificates endpoint:

nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/storage/ssl_certificates"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/storage/ssl_certificates"
output
json
[
  {
    "description": "managed SSL file",
    "file": "/etc/hapee-3.0/ssl/newcert.pem",
    "storage_name": "newcert.pem"
  }
]
output
json
[
  {
    "description": "managed SSL file",
    "file": "/etc/hapee-3.0/ssl/newcert.pem",
    "storage_name": "newcert.pem"
  }
]
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/storage/ssl_certificates"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/storage/ssl_certificates"
output
json
[
  {
    "description": "managed SSL file",
    "file": "/etc/hapee-2.8/ssl/newcert.pem",
    "storage_name": "newcert.pem"
  }
]
output
json
[
  {
    "description": "managed SSL file",
    "file": "/etc/hapee-2.8/ssl/newcert.pem",
    "storage_name": "newcert.pem"
  }
]

If there are no certificates present, the call returns an empty array [].

List a specific certificate Jump to heading

To get information about a specific certificate, make a GET request with the filename of the certificate. Below, we get information about the certificate named newcert.pem:

nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/storage/ssl_certificates/newcert.pem"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/storage/ssl_certificates/newcert.pem"
output
json
{
  "description": "managed SSL file",
  "domains": "example.com",
  "file": "/etc/hapee-3.0/ssl/newcert.pem",
  "issuers": "example-issuer",
  "not_after": "2025-08-13T09:00:00.000Z",
  "not_before": "2023-10-27T19:25:15.000Z",
  "size": 4385,
  "storage_name": "newcert.pem"
}
output
json
{
  "description": "managed SSL file",
  "domains": "example.com",
  "file": "/etc/hapee-3.0/ssl/newcert.pem",
  "issuers": "example-issuer",
  "not_after": "2025-08-13T09:00:00.000Z",
  "not_before": "2023-10-27T19:25:15.000Z",
  "size": 4385,
  "storage_name": "newcert.pem"
}
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/storage/ssl_certificates/newcert.pem"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/storage/ssl_certificates/newcert.pem"
output
json
{
  "description": "managed SSL file",
  "domains": "example.com",
  "file": "/etc/hapee-2.8/ssl/newcert.pem",
  "issuers": "example-issuer",
  "not_after": "2025-08-13T09:00:00.000Z",
  "not_before": "2023-10-27T19:25:15.000Z",
  "size": 4385,
  "storage_name": "newcert.pem"
}
output
json
{
  "description": "managed SSL file",
  "domains": "example.com",
  "file": "/etc/hapee-2.8/ssl/newcert.pem",
  "issuers": "example-issuer",
  "not_after": "2025-08-13T09:00:00.000Z",
  "not_before": "2023-10-27T19:25:15.000Z",
  "size": 4385,
  "storage_name": "newcert.pem"
}

Upload a certficate Jump to heading

To add a certficate, make a POST request to the ssl_certificates endpoint, specifying the filename of your certificate as the value for the parameter -f file_upload. Note that prior to making the POST request, you must first capture the current version in an environment variable (CFGVER in this example) and use the value in your request. Below, we add a new certificate named newcert.pem:

Concatenate your certificates

If your certificate, private key, and intermediate certificates or certificate chain are in different files, concatenate them into one file in .PEM format and upload the concatenated certificate file:

Example:

nix
cat website.crt website.key myCA.pem > webcombined.pem
nix
cat website.crt website.key myCA.pem > webcombined.pem
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X POST \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -f file_upload=@./newcert.pem \
  "http://localhost:5555/v3/services/haproxy/storage/ssl_certificates?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X POST \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -f file_upload=@./newcert.pem \
  "http://localhost:5555/v3/services/haproxy/storage/ssl_certificates?version=$CFGVER"
output
json
{
  "description": "managed SSL file",
  "domains": "example.com",
  "file": "/etc/hapee-3.0/ssl/newcert.pem",
  "issuers": "example-issuer",
  "not_after": "2025-08-13T09:00:00.000Z",
  "not_before": "2023-10-27T19:25:15.000Z",
  "size": 4385,
  "storage_name": "newcert.pem"
}
output
json
{
  "description": "managed SSL file",
  "domains": "example.com",
  "file": "/etc/hapee-3.0/ssl/newcert.pem",
  "issuers": "example-issuer",
  "not_after": "2025-08-13T09:00:00.000Z",
  "not_before": "2023-10-27T19:25:15.000Z",
  "size": 4385,
  "storage_name": "newcert.pem"
}
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X POST \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -f file_upload=@./newcert.pem \
  "http://localhost:5555/v2/services/haproxy/storage/ssl_certificates?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X POST \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -f file_upload=@./newcert.pem \
  "http://localhost:5555/v2/services/haproxy/storage/ssl_certificates?version=$CFGVER"
output
json
{
  "description": "managed SSL file",
  "domains": "example.com",
  "file": "/etc/hapee-2.8/ssl/newcert.pem",
  "issuers": "example-issuer",
  "not_after": "2025-08-13T09:00:00.000Z",
  "not_before": "2023-10-27T19:25:15.000Z",
  "size": 4385,
  "storage_name": "newcert.pem"
}
output
json
{
  "description": "managed SSL file",
  "domains": "example.com",
  "file": "/etc/hapee-2.8/ssl/newcert.pem",
  "issuers": "example-issuer",
  "not_after": "2025-08-13T09:00:00.000Z",
  "not_before": "2023-10-27T19:25:15.000Z",
  "size": 4385,
  "storage_name": "newcert.pem"
}

Replace a certificate Jump to heading

To replace an existing certificate, make a PUT request to the ssl_certificates endpoint, passing the filename of the certificate at the end of the URL path. Note that prior to making the PUT request, you must first capture the current version in an environment variable (CFGVER in this example) and use the value in your request. Here we replace the certificate named newcert.pem with the contents of a certificate file named updatedcert.pem. Note that the original name of the certificate does not change, only its contents:

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X PUT \
  --user admin:adminpwd \
  -H "Content-Type: text/plain" \
  --data-binary @./updatedcert.pem \
  "http://localhost:5555/v3/services/haproxy/storage/ssl_certificates/newcert.pem?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X PUT \
  --user admin:adminpwd \
  -H "Content-Type: text/plain" \
  --data-binary @./updatedcert.pem \
  "http://localhost:5555/v3/services/haproxy/storage/ssl_certificates/newcert.pem?version=$CFGVER"
output
json
{
  "description": "managed SSL file",
  "domains": "example.com",
  "file": "/etc/hapee-3.0/ssl/newcert.pem",
  "issuers": "example-issuer",
  "not_after": "2026-09-13T09:00:00.000Z",
  "not_before": "2024-11-27T19:25:15.000Z",
  "size": 4390,
  "storage_name": "newcert.pem"
}
output
json
{
  "description": "managed SSL file",
  "domains": "example.com",
  "file": "/etc/hapee-3.0/ssl/newcert.pem",
  "issuers": "example-issuer",
  "not_after": "2026-09-13T09:00:00.000Z",
  "not_before": "2024-11-27T19:25:15.000Z",
  "size": 4390,
  "storage_name": "newcert.pem"
}
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X PUT \
  --user admin:adminpwd \
  -H "Content-Type: text/plain" \
  --data-binary @./newcert.pem \
  "http://localhost:5555/v2/services/haproxy/storage/ssl_certificates/newcert.pem?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X PUT \
  --user admin:adminpwd \
  -H "Content-Type: text/plain" \
  --data-binary @./newcert.pem \
  "http://localhost:5555/v2/services/haproxy/storage/ssl_certificates/newcert.pem?version=$CFGVER"
output
json
{
  "description": "managed SSL file",
  "domains": "example.com",
  "file": "/etc/hapee-2.8/ssl/newcert.pem",
  "issuers": "example-issuer",
  "not_after": "2026-09-13T09:00:00.000Z",
  "not_before": "2024-11-27T19:25:15.000Z",
  "size": 4390,
  "storage_name": "newcert.pem"
}
output
json
{
  "description": "managed SSL file",
  "domains": "example.com",
  "file": "/etc/hapee-2.8/ssl/newcert.pem",
  "issuers": "example-issuer",
  "not_after": "2026-09-13T09:00:00.000Z",
  "not_before": "2024-11-27T19:25:15.000Z",
  "size": 4390,
  "storage_name": "newcert.pem"
}

If you receive an error like the following, the certificate you are trying to replace does not exist: {"code":404,"message":"missing object: file cert.pem doesn't exist in dir: /etc/hapee-3.0/ssl"}. Be sure to upload the certificate before updating it.

Delete a certificate Jump to heading

To delete a certificate, use the DELETE method, passing the filename of the certificate as part of the URL path. Note that prior to making the DELETE request, you must first capture the current version in an environment variable (CFGVER in this example) and use the value in your request. Below we delete the certificate named newcert.pem:

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X DELETE \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/certificates/myservers?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X DELETE \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/certificates/myservers?version=$CFGVER"

There is no output from this command.

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X DELETE \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/certificates/myservers?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X DELETE \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/certificates/myservers?version=$CFGVER"

There is no output from this command.

If you receive an error message like the following, the certificate you are trying to delete does not exist: {"code":404,"message":"missing object: file cert.pem doesn't exist in dir: /etc/hapee-3.0/ssl"}.

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

Previous page Manage default settings Next page Advanced features
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences