Installation
Install the HAProxy Data Plane API on HAProxy ALOHA
Available since
- HAProxy ALOHA firmware 13.0
- HAProxy ALOHA hardware appliance 5300
Install the Data Plane API Jump to heading
To install the Data Plane API:
-
If your HAProxy ALOHA host is a virtual appliance instead of hardware, you need to create an additional partition large enough to contain the files.
-
Attach a new hard disk to the virtual machine. It should be 30 GB or larger. See the documentation for your hypervisor or cloud service.
-
Power on your HAProxy ALOHA Virtual Appliance.
-
Log in to your HAProxy ALOHA web UI as an administrator. The web UI runs at port 4444.
-
Select the Tools tab, then edit the file
/etc/config.rc
through the File Manager. Add the following directives at the end of theservice system
section, then click Save:textapp_auto_mountapp_auto_formatapp_device_size 30000000000textapp_auto_mountapp_auto_formatapp_device_size 30000000000where:
app_auto_mount
automatically mounts the partition on/app
.app_auto_format
automatically formats the/app
partition, if needed.app_device_size <Size in bytes>
specifies the size in bytes of the/app
partition. Here we set it to 30 GB.
-
Select the Setup tab, then click Save to save your modifications.
-
Restart HAProxy ALOHA by going to the Setup tab and clicking Reboot.
-
-
Obtain your credentials for accessing HAProxy ALOHA downloads. You can create a new support ticket in the HAProxy Technologies Customer Portal to request your credentials.
-
Go to the ALOHA downloads page, navigate into the folder for your firmware and then into the
packages
folder. Enter your credentials to access the folder.Download the latest
management-aloha<VERSION>.img
disk image. -
Log in to your HAProxy ALOHA web UI as an administrator.
-
Go to the Tools tab, then use the File manager to upload the
management-aloha<VERSION>.img
disk image to the directory/app/images/
. -
Go to the Setup tab and click Reboot.
-
Go back to the Tools tab and check in the File Manager that the
/app/management
directory is populated. -
Check that the dataplaneapi service is started on the Services tab.
-
Optional: To change the default settings of the Data Plane API, edit the file
/app/management/var/lib/dataplaneapi/dataplaneapi.yaml
and then restart the dataplaneapi service on the Services tab.
Update to a newer version of the API Jump to heading
To update to a newer version of the API, follow these steps:
-
Obtain your credentials for accessing HAProxy ALOHA downloads. You can create a new support ticket in the HAProxy Technologies Customer Portal to request your credentials.
-
Go to the ALOHA downloads page, navigate into the folder for your firmware and then into the
packages
folder. Enter your credentials to access the folder.Download the latest
management-aloha<VERSION>.img
disk image. -
Log in to your HAProxy ALOHA web UI as an administrator.
-
In the Services tab, stop the dataplaneapi service.
-
Go to the Tools tab, then use the File manager to upload the
management-aloha<VERSION>.img
disk image to the directory/app/images/
. -
Reboot the virtual appliance through the Setup tab.
-
Check that the dataplaneapi service is started in the Services tab.
You can also verify which version of the API is installed by running the following command from the CLI:
nix/app/management/usr/sbin/dataplaneapi --versionnix/app/management/usr/sbin/dataplaneapi --version
Enable HTTPS Jump to heading
To enable HTTPS for Data Plane API with HAProxy ALOHA:
Default certificate
HAProxy ALOHA includes a default self-signed certificate and private key that you can use for testing. If you opt to use these, you do not need to upload or create an additional certificate and key, as described in the subsequent steps.
-
Upload your existing certificate and private key or create a new one. See HAProxy ALOHA SSL for more information.
Tip
You will need to provide the full file path to your certificate and private key when you update your Data Plane API configuration in the subsequent steps. Certificates and keys you create or upload using the SSL tab are placed into
/etc/ssl/frontends/<name you specified for the certificate>/
. Use the File Manager in the Tools tab to browse to this location and verify the file path of your certificate and key. -
With your certificate and private key files in place, select the Tools tab, then edit the file
/app/management/var/lib/dataplaneapi/dataplaneapi.yaml
. -
The default configuration for the Data Plane API on HAProxy ALOHA includes a
tls
section that references the default self-signed certificate. Replace the existing values with your certificate files and setscheme
tohttps
as follows.Tip
If you are opting to use the default self-signed certificate included with HAProxy ALOHA, keep the default values for
tls_certificate
andtls_key
. Note that you should use this only for testing or with internal users, as there are security implications for using a self-signed certificate.Set the following:
- The
scheme
tohttps
. Note that you can also have an entry forhttp
, but you must specify different ports forport
andtls_port
to enable both HTTP and HTTPS. - The port for TLS connections as
tls_port
. This must be a different port than you specify forport
if you intend to have both HTTP and HTTPS connections active. - The path to the certificate file to use with TLS connections as
tls_certificate
. - The path to the private key to use with TLS connections as
tls_key
.
dataplaneapi.hclhcldataplaneapi {host = "0.0.0.0"port = 5555scheme = ["https"]...tls {tls_port = 6443tls_certificate: "/etc/ssl/frontends/myapp/server-cert.pem"tls_key: "/etc/ssl/frontends/myapp/server-key.pem"}...}dataplaneapi.hclhcldataplaneapi {host = "0.0.0.0"port = 5555scheme = ["https"]...tls {tls_port = 6443tls_certificate: "/etc/ssl/frontends/myapp/server-cert.pem"tls_key: "/etc/ssl/frontends/myapp/server-key.pem"}...}dataplaneapi.ymlyamldataplaneapi:host: 0.0.0.0port: 5555scheme:- https...tls:tls_port: 6443tls_certificate: /etc/ssl/frontends/myapp/server-cert.pemtls_key: /etc/ssl/frontends/myapp/server-key.pem...dataplaneapi.ymlyamldataplaneapi:host: 0.0.0.0port: 5555scheme:- https...tls:tls_port: 6443tls_certificate: /etc/ssl/frontends/myapp/server-cert.pemtls_key: /etc/ssl/frontends/myapp/server-key.pem... - The
-
Click Save.
-
Navigate to the Services tab and reload the dataplaneapi service.
You can test the HTTPS connection to the Data Plane API using curl
, providing your username and password that you defined in the userlist
during installation. The following example is for Data Plane API 3.0 (v3
):
nix
curl -k --user <username>:<password> -X GET https://localhost:6443/v3/info
nix
curl -k --user <username>:<password> -X GET https://localhost:6443/v3/info
outputjson
{"api":{"build_date":"2025-01-17T17:13:45.000Z","version":"v3.0.4-ee1 d354a7ec"},"system":{}}
outputjson
{"api":{"build_date":"2025-01-17T17:13:45.000Z","version":"v3.0.4-ee1 d354a7ec"},"system":{}}
You can optionally set the following properties in the tls
section:
Option | Description |
---|---|
tls_host |
The IP to listen on for HTTPS. If you don’t specify a value, it’s the same as host . |
tls_listen_limit |
Limits the number of outstanding requests. |
tls_keep_alive |
Sets the TCP keep-alive timeouts on accepted connections. |
tls_read_timeout |
Maximum duration before timing out read operation of the request. |
tls_write_timeout |
Maximum duration before timing out write operation of the response. |
tls_ca |
The certificate authority file to be used when you enable mTLS authentication. When you provide this option, basic authentication with the Data Plane API is disabled. You will need to authenticate using a client certificate and key. |
Enable mTLS Jump to heading
If you need to perform client certificate authentication, also known as mTLS, for connections to the Data Plane API, you can set an additional parameter in the configuration, tls_ca
, which sets the certificate authority with which to authenticate client certificates. To enable this behavior:
-
Use the File Manager on the Tools tab to upload your CA file. You can upload this to the same directory HAProxy ALOHA places certificates and keys you create or upload through the SSL tab which is
/etc/ssl/frontends/etc/ssl/frontends/<name you specified for the certificate>/
. -
Add this line to your Data Plane API configuration which specifies the path to your CA file:
dataplaneapi.hclhcldataplaneapi {host = "0.0.0.0"port = 5555scheme = ["https"]...tls {tls_port = 6443tls_certificate: "/etc/ssl/frontends/myapp/server-cert.pem"tls_key: "/etc/ssl/frontends/myapp/server-key.pem"tls_ca: "/etc/ssl/frontends/myapp/ca-cert.pem"}...}dataplaneapi.hclhcldataplaneapi {host = "0.0.0.0"port = 5555scheme = ["https"]...tls {tls_port = 6443tls_certificate: "/etc/ssl/frontends/myapp/server-cert.pem"tls_key: "/etc/ssl/frontends/myapp/server-key.pem"tls_ca: "/etc/ssl/frontends/myapp/ca-cert.pem"}...}dataplaneapi.ymlyamldataplaneapi:host: 0.0.0.0port: 5555scheme:- https...tls:tls_port: 6443tls_certificate: /etc/ssl/frontends/myapp/server-cert.pemtls_key: /etc/ssl/frontends/myapp/server-key.pemtls_ca: /etc/ssl/frontends/myapp/ca-cert.pem...dataplaneapi.ymlyamldataplaneapi:host: 0.0.0.0port: 5555scheme:- https...tls:tls_port: 6443tls_certificate: /etc/ssl/frontends/myapp/server-cert.pemtls_key: /etc/ssl/frontends/myapp/server-key.pemtls_ca: /etc/ssl/frontends/myapp/ca-cert.pem... -
Click Save.
-
Navigate to the Services tab and reload the dataplaneapi service.
Note that enabling mTLS in this way means that instead of authenticating with the Data Plane API using a username and password, you will use a client certificate and key.
You can test the HTTPS connection to the Data Plane API using curl
, providing your client certificate and key. The following example is for Data Plane API 3.0 (v3
):
nix
curl -k --cert client-cert.pem --key client-key.pem -X GET https://localhost:6443/v3/info
nix
curl -k --cert client-cert.pem --key client-key.pem -X GET https://localhost:6443/v3/info
outputjson
{"api":{"build_date":"2025-01-17T17:13:45.000Z","version":"v3.0.4-ee1 d354a7ec"},"system":{}}
outputjson
{"api":{"build_date":"2025-01-17T17:13:45.000Z","version":"v3.0.4-ee1 d354a7ec"},"system":{}}
Do you have any suggestions on how we can improve the content of this page?