Installation

Install the HAProxy Data Plane API on HAProxy ALOHA

On this page

Available since

  • HAProxy ALOHA firmware 13.0
  • HAProxy ALOHA hardware appliance 5300

Install the HAProxy Data Plane API Jump to heading

To install the HAProxy Data Plane API:

  1. 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 the service system section, then click Save:

      text
      app_auto_mount
      app_auto_format
      app_device_size 30000000000
      text
      app_auto_mount
      app_auto_format
      app_device_size 30000000000

      where:

      • 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.

  2. Obtain your credentials for accessing HAProxy ALOHA downloads. You can create a new support ticket to request your credentials.

  3. 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.

  4. Log in to your HAProxy ALOHA web UI as an administrator.

  5. Go to the Tools tab, then use the File manager to upload the management-aloha<VERSION>.img disk image to the directory /app/images/.

  6. Go to the Setup tab and click Reboot.

  7. Go back to the Tools tab and check in the File Manager that the /app/management directory is populated.

  8. Check that the dataplaneapi service is started on the Services tab.

  9. Optional: To change the default settings of the HAProxy Data Plane API, edit the file /app/management/var/lib/dataplaneapi/dataplaneapi.yaml and then restart the dataplaneapi service on the Services tab.

Verify that the API works Jump to heading

To verify that the API is running properly, try calling the info API endpoint:

nix
curl --request GET --user admin:admin http://localhost:5555/v3/info
nix
curl --request GET --user admin:admin http://localhost:5555/v3/info
output
json
{"api":{"build_date":"2026-03-10T18:03:47.000Z","version":"v3.3.1-ee1 7d90e2d1"},"system":{}}
output
json
{"api":{"build_date":"2026-03-10T18:03:47.000Z","version":"v3.3.1-ee1 7d90e2d1"},"system":{}}

Add a user and password Jump to heading

To set the username and password you use to access the HAProxy Data Plane API, add a new user:

  1. Go to the Tools tab and click Launch a terminal.

  2. Use the useradd command to create a new user. In this example, we create a user named alex:

    nix
    sudo useradd -m --base-dir /app/home --home-dir /app/home/alex -r -s /bin/sh alex
    nix
    sudo useradd -m --base-dir /app/home --home-dir /app/home/alex -r -s /bin/sh alex

  3. Use the passwd command to set the user’s password. Pass the user’s name to the command as an argument:

    nix
    sudo passwd alex
    nix
    sudo passwd alex

    You’ll be prompted to enter a password.

    output
    text
    New password:
    Retype new password:
    passwd: password updated successfully
    output
    text
    New password:
    Retype new password:
    passwd: password updated successfully

  4. Verify the username and password by calling the info API endpoint:

    nix
    curl --request GET --user alex:mypass http://localhost:5555/v3/info
    nix
    curl --request GET --user alex:mypass http://localhost:5555/v3/info
    output
    json
    {"api":{"build_date":"2026-03-10T18:03:47.000Z","version":"v3.3.1-ee1 7d90e2d1"},"system":{}}
    output
    json
    {"api":{"build_date":"2026-03-10T18:03:47.000Z","version":"v3.3.1-ee1 7d90e2d1"},"system":{}}

Update to a newer version of the API Jump to heading

To update to a newer version of the API, follow these steps:

  1. Obtain your credentials for accessing HAProxy ALOHA downloads. You can create a new support ticket to request your credentials.

  2. 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.

  3. Log in to your HAProxy ALOHA web UI as an administrator.

  4. In the Services tab, stop the dataplaneapi service.

  5. Go to the Tools tab, then use the File manager to upload the management-aloha<VERSION>.img disk image to the directory /app/images/.

  6. Reboot the virtual appliance through the Setup tab.

  7. 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 --version
    nix
    /app/management/usr/sbin/dataplaneapi --version

Enable HTTPS Jump to heading

To enable HTTPS for HAProxy 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.

  1. 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 HAProxy 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.

  2. With your certificate and private key files in place, select the Tools tab, then edit the file /app/management/var/lib/dataplaneapi/dataplaneapi.yaml.

  3. The default configuration for the HAProxy 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 set scheme to https 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 and tls_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 to https. Note that you can also have an entry for http, but you must specify different ports for port and tls_port to enable both HTTP and HTTPS.
    • The port for TLS connections as tls_port. This must be a different port than you specify for port 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.hcl
    hcl
    dataplaneapi {
      host = "0.0.0.0"
      port = 5555
      scheme = ["https"]
      ...
      tls {
        tls_port = 6443
        tls_certificate: "/etc/ssl/frontends/myapp/server-cert.pem"
        tls_key: "/etc/ssl/frontends/myapp/server-key.pem"
      }
      ...
    }
    dataplaneapi.hcl
    hcl
    dataplaneapi {
      host = "0.0.0.0"
      port = 5555
      scheme = ["https"]
      ...
      tls {
        tls_port = 6443
        tls_certificate: "/etc/ssl/frontends/myapp/server-cert.pem"
        tls_key: "/etc/ssl/frontends/myapp/server-key.pem"
      }
      ...
    }
    dataplaneapi.yml
    yaml
    dataplaneapi:
      host: 0.0.0.0
      port: 5555
      scheme:
      - https
      ...
      tls:
        tls_port: 6443
        tls_certificate: /etc/ssl/frontends/myapp/server-cert.pem
        tls_key: /etc/ssl/frontends/myapp/server-key.pem
      ...
    dataplaneapi.yml
    yaml
    dataplaneapi:
      host: 0.0.0.0
      port: 5555
      scheme:
      - https
      ...
      tls:
        tls_port: 6443
        tls_certificate: /etc/ssl/frontends/myapp/server-cert.pem
        tls_key: /etc/ssl/frontends/myapp/server-key.pem
      ...

  4. Click Save.

  5. Navigate to the Services tab and reload the dataplaneapi service.

You can test the HTTPS connection to the HAProxy Data Plane API using curl, providing your username and password that you defined in the userlist during installation. The following example is for HAProxy Data Plane API 3.0 (v3):

nix
curl -k --user <username>:<password> --request GET https://localhost:6443/v3/info
nix
curl -k --user <username>:<password> --request GET https://localhost:6443/v3/info
output
json
{"api":{"build_date":"2025-01-17T17:13:45.000Z","version":"v3.0.4-ee1 d354a7ec"},"system":{}}
output
json
{"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 HAProxy 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 HAProxy 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:

  1. 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>/.

  2. Add this line to your HAProxy Data Plane API configuration which specifies the path to your CA file:

    dataplaneapi.hcl
    hcl
    dataplaneapi {
      host = "0.0.0.0"
      port = 5555
      scheme = ["https"]
      ...
      tls {
        tls_port = 6443
        tls_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.hcl
    hcl
    dataplaneapi {
      host = "0.0.0.0"
      port = 5555
      scheme = ["https"]
      ...
      tls {
        tls_port = 6443
        tls_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.yml
    yaml
    dataplaneapi:
      host: 0.0.0.0
      port: 5555
      scheme:
      - https
      ...
      tls:
        tls_port: 6443
        tls_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.yml
    yaml
    dataplaneapi:
      host: 0.0.0.0
      port: 5555
      scheme:
      - https
      ...
      tls:
        tls_port: 6443
        tls_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
      ...

  3. Click Save.

  4. Navigate to the Services tab and reload the dataplaneapi service.

Note that enabling mTLS in this way means that instead of authenticating with the HAProxy Data Plane API using a username and password, you will use a client certificate and key.

You can test the HTTPS connection to the HAProxy Data Plane API using curl, providing your client certificate and key. The following example is for HAProxy Data Plane API 3.0 (v3):

nix
curl -k --cert client-cert.pem --key client-key.pem --request GET https://localhost:6443/v3/info
nix
curl -k --cert client-cert.pem --key client-key.pem --request GET https://localhost:6443/v3/info
output
json
{"api":{"build_date":"2025-01-17T17:13:45.000Z","version":"v3.0.4-ee1 d354a7ec"},"system":{}}
output
json
{"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?

Previous page Install on HAProxy Enterprise Next page Upgrade
© 2026 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences