Installation
Install HAProxy Data Plane API on HAProxy Enterprise
This section describes how to install HAProxy Data Plane API on HAProxy Enterprise.
HAProxy Data Plane API and HAProxy Fusion
If your load balancer is managed by HAProxy Fusion, use HAProxy Fusion API instead of HAProxy Data Plane API. HAProxy Fusion installs and uses HAProxy Data Plane API on load balancer nodes that it manages. Don’t reinstall HAProxy Data Plane API on nodes managed by HAProxy Fusion.
Version 3.0 contains breaking changes
If you’re installing HAProxy Data Plane API 3.x, know that it changes several conventions that were present in version 2.x, and that upgrading to 3.x will require you to call the API endpoints differently. See the release notes for more details.
Run the API using systemd Jump to heading
When you run HAProxy Enterprise on Linux, you must install HAProxy Data Plane API as an additional step. The API then runs as a systemd service.
-
Install HAProxy Data Plane API x86-64 package.
Install the softwarenixsudo apt-get install hapee-extras-dataplaneapi33nixsudo apt-get install hapee-extras-dataplaneapi33nixsudo yum install hapee-extras-dataplaneapi33 --allowerasingnixsudo yum install hapee-extras-dataplaneapi33 --allowerasingnixsudo zypper install hapee-extras-dataplaneapi33nixsudo zypper install hapee-extras-dataplaneapi33nixsudo pkg install hapee-extras-dataplaneapi33nixsudo pkg install hapee-extras-dataplaneapi33nixsudo apt-get install hapee-extras-dataplaneapi32nixsudo apt-get install hapee-extras-dataplaneapi32nixsudo yum install hapee-extras-dataplaneapi32 --allowerasingnixsudo yum install hapee-extras-dataplaneapi32 --allowerasingnixsudo zypper install hapee-extras-dataplaneapi32nixsudo zypper install hapee-extras-dataplaneapi32nixsudo pkg install hapee-extras-dataplaneapi32nixsudo pkg install hapee-extras-dataplaneapi32nixsudo apt-get install hapee-extras-dataplaneapi31nixsudo apt-get install hapee-extras-dataplaneapi31nixsudo yum install hapee-extras-dataplaneapi31 --allowerasingnixsudo yum install hapee-extras-dataplaneapi31 --allowerasingnixsudo zypper install hapee-extras-dataplaneapi31nixsudo zypper install hapee-extras-dataplaneapi31nixsudo pkg install hapee-extras-dataplaneapi31nixsudo pkg install hapee-extras-dataplaneapi31nixsudo apt-get install hapee-extras-dataplaneapi30nixsudo apt-get install hapee-extras-dataplaneapi30nixsudo yum install hapee-extras-dataplaneapi30 --allowerasingnixsudo yum install hapee-extras-dataplaneapi30 --allowerasingnixsudo zypper install hapee-extras-dataplaneapi30nixsudo zypper install hapee-extras-dataplaneapi30nixsudo pkg install hapee-extras-dataplaneapi30nixsudo pkg install hapee-extras-dataplaneapi30nixsudo apt-get install hapee-extras-dataplaneapi29nixsudo apt-get install hapee-extras-dataplaneapi29nixsudo yum install hapee-extras-dataplaneapi29 --allowerasingnixsudo yum install hapee-extras-dataplaneapi29 --allowerasingnixsudo zypper install hapee-extras-dataplaneapi29nixsudo zypper install hapee-extras-dataplaneapi29nixsudo pkg install hapee-extras-dataplaneapi29nixsudo pkg install hapee-extras-dataplaneapi29 -
Ensure that your HAProxy Enterprise configuration has a
stats socketline in theglobalsection; this enables the HAProxy Runtime API. HAProxy Data Plane API integrates with the Runtime API to make some configuration changes without needing to reload the load balancer.hapee-lb.cfghaproxyglobalstats socket /var/run/hapee-3.3/hapee-lb.sock user hapee-lb group hapee mode 660 level admin expose-fd listenershapee-lb.cfghaproxyglobalstats socket /var/run/hapee-3.3/hapee-lb.sock user hapee-lb group hapee mode 660 level admin expose-fd listeners -
Configure the Basic authentication credentials you’ll use to access the API by setting the username and password in the HAProxy Data Plane API configuration file,
/etc/hapee-extras/dataplaneapi.yml. Add auserblock to the HAProxy Data Plane API configuration file, and set the password with thepasswordfield. If you setinsecuretotrue, set a cleartext password. If you setinsecuretofalse, set an MD5, SHA-256, or SHA-512 hash of the password.Configuration file on versions <= 2.7
For HAProxy Data Plane API version 2.7 and older, the configuration file is named
/etc/hapee-extras/dataplaneapi.hcl. It uses the HCL syntax.dataplaneapi.ymlyamldataplaneapi:user:- name: admininsecure: truepassword: adminpwddataplaneapi.ymlyamldataplaneapi:user:- name: admininsecure: truepassword: adminpwd -
Enable and restart the service:
nixsudo systemctl enable hapee-extras-dataplaneapisudo systemctl restart hapee-extras-dataplaneapinixsudo systemctl enable hapee-extras-dataplaneapisudo systemctl restart hapee-extras-dataplaneapi
Run the API in Docker Jump to heading
Prerequisite
Run HAProxy Enterprise as a Docker container. It hosts HAProxy Data Plane API.
When you run HAProxy Enterprise as a Docker container, HAProxy Data Plane API is included and listens at port 5555. The username and password for accessing it are defined in the file hapee-extras/dataplaneapi.yml.
Configuration file on versions <= 2.7
For HAProxy Data Plane API version 2.7 and older, the configuration file is named /etc/hapee-extras/dataplaneapi.hcl. It uses the HCL syntax.
-
Find the
userconfiguration section inside thedataplaneapi.ymlfile.Example:
dataplaneapi.ymlyamluser:- insecure: truepassword: v7xkLr4Z4Qlcname: admindataplaneapi.ymlyamluser:- insecure: truepassword: v7xkLr4Z4Qlcname: admin -
Verify that the API is working by calling the
infoendpoint. In the example below, we use the username and password that we retrieved during the last step.nixcurl --request GET --user admin:v7xkLr4Z4Qlc http://localhost:5555/v3/infonixcurl --request GET --user admin:v7xkLr4Z4Qlc http://localhost:5555/v3/infooutputjson{"api":{"build_date":"2025-07-11T15:43:53.000Z","version":"v3.0.12-ee2 b3359a8f"},"system":{}}outputjson{"api":{"build_date":"2025-07-11T15:43:53.000Z","version":"v3.0.12-ee2 b3359a8f"},"system":{}}
Change the password Jump to heading
To change the password you use to access the API:
-
Edit
dataplaneapi.ymland change the password in theuserblock. If you setinsecuretotrue, set a cleartext password. If you setinsecuretofalse, set an MD5, SHA-256, or SHA-512 hash of the password.dataplaneapi.ymlyamluser:- name: admininsecure: truepassword: adminpwddataplaneapi.ymlyamluser:- name: admininsecure: truepassword: adminpwd -
Restart the service or Docker container:
nixsudo systemctl restart hapee-extras-dataplaneapinixsudo systemctl restart hapee-extras-dataplaneapinixsudo docker restart <NAME OF HAPROXY ENTERPRISE CONTAINER>nixsudo docker restart <NAME OF HAPROXY ENTERPRISE CONTAINER> -
Verify that the API is working by calling the
infoendpoint with the new password.nixcurl --request GET --user admin:adminpwd http://localhost:5555/v3/infonixcurl --request GET --user admin:adminpwd http://localhost:5555/v3/infooutputjson{"api":{"build_date":"2025-07-11T15:43:53.000Z","version":"v3.0.12-ee2 b3359a8f"},"system":{}}outputjson{"api":{"build_date":"2025-07-11T15:43:53.000Z","version":"v3.0.12-ee2 b3359a8f"},"system":{}}
Change the IP address and port Jump to heading
By default, HAProxy Data Plane API listens on all IP addresses at TCP port 5555. You can change the listening IP address and port by editing the HAProxy Data Plane API configuration file.
-
Change the
hostand/orportfields in thedataplaneapiblock.This example changes the
hostto192.168.50.20and theportfrom its default of5555to5557.dataplaneapi.ymlyamldataplaneapi:host: 192.168.50.20port: 5557dataplaneapi.ymlyamldataplaneapi:host: 192.168.50.20port: 5557Alternatively, set the
HOSTandPORTenvironment variables. If you’re running the API as a systemd service, add those variables to the following file, which the service reads at startup:- On Debian/Ubuntu,
/etc/default/hapee-extras-dataplaneapi - On Alma/Oracle/Red Hat/Rocky,
/etc/sysconfig/hapee-extras-dataplaneapi
hapee-extras-dataplaneapiiniHOST=192.168.50.20PORT=5557hapee-extras-dataplaneapiiniHOST=192.168.50.20PORT=5557 - On Debian/Ubuntu,
-
Restart the service or Docker container:
nixsudo systemctl restart hapee-extras-dataplaneapinixsudo systemctl restart hapee-extras-dataplaneapinixsudo docker restart <NAME OF HAPROXY ENTERPRISE CONTAINER>nixsudo docker restart <NAME OF HAPROXY ENTERPRISE CONTAINER>
Verify that the API works Jump to heading
To verify that the API is running properly, try calling the info API endpoint.
nix
nix
outputjson
outputjson
If you get a permission denied error:
outputjson
outputjson
This often means that the user who runs the API doesn’t have access to the Runtime API socket. Check that you added them to the system group hapee, log out and back in again, then try it again.
If you receive an error such as 400 Bad Request or Client sent an HTTP request to an HTTPS server, HTTPS may be enabled. Try the curl command again with the -k option and specify HTTPS in your URL:
nix
nix
Enable HTTPS Jump to heading
Using HAProxy Fusion?
For HAProxy Enterprise instances managed by HAProxy Fusion, HTTPS is enabled by default. The appropriate certificates are already in place. There is no need to change the TLS settings if your HAProxy Enterprise instance is managed by HAProxy Fusion.
To enable HTTPS for accessing HAProxy Data Plane API, you must add a tls section to your configuration file and set the scheme to https:
-
Add the following to your HAProxy Data Plane API configuration file:
dataplaneapi.ymlyamldataplaneapi:host: 0.0.0.0port: 5555scheme:- https...tls:tls_port: 6443tls_certificate: /etc/hapee-3.3/certs/server-cert.pemtls_key: /etc/hapee-3.3/certs/server-key.pem...dataplaneapi.ymlyamldataplaneapi:host: 0.0.0.0port: 5555scheme:- https...tls:tls_port: 6443tls_certificate: /etc/hapee-3.3/certs/server-cert.pemtls_key: /etc/hapee-3.3/certs/server-key.pem...Set the following:
- The
schemetohttps. Note that you can also have an entry forhttp, but you must specify different ports forportandtls_portto enable both HTTP and HTTPS. - The port for TLS connections as
tls_port. This must be a different port than you specify forportif you intend to have both HTTP and HTTPS connections active. - The path to the certificate file to use with TLS connections as
tls_certificate. If using Docker, you’ll need to add thecertsdirectory to the volume mount. - The path to the private key to use with TLS connections as
tls_key.
- The
-
Restart the service or Docker container:
nixsudo systemctl restart hapee-extras-dataplaneapinixsudo systemctl restart hapee-extras-dataplaneapinixsudo docker restart <NAME OF HAPROXY ENTERPRISE CONTAINER>nixsudo docker restart <NAME OF HAPROXY ENTERPRISE CONTAINER>
You can test the HTTPS connection to HAProxy Data Plane API using curl, providing your username and password that you defined in the user section during installation. The following example is for HAProxy Data Plane API 3.0 (v3):
nix
nix
outputjson
outputjson
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 with mTLS authentication. Providing this option disables basic authentication. 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 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:
-
Add this line to your HAProxy Data Plane API configuration which specifies the path to your CA file:
dataplaneapi.ymlyamldataplaneapi:host: 0.0.0.0port: 5555scheme:- https...tls:tls_port: 6443tls_certificate: /etc/hapee-3.3/certs/server-cert.pemtls_key: /etc/hapee-3.3/certs/server-key.pemtls_ca: /etc/hapee-3.3/certs/ca-cert.pem...dataplaneapi.ymlyamldataplaneapi:host: 0.0.0.0port: 5555scheme:- https...tls:tls_port: 6443tls_certificate: /etc/hapee-3.3/certs/server-cert.pemtls_key: /etc/hapee-3.3/certs/server-key.pemtls_ca: /etc/hapee-3.3/certs/ca-cert.pem... -
Restart the service or Docker container:
nixsudo systemctl restart hapee-extras-dataplaneapinixsudo systemctl restart hapee-extras-dataplaneapinixsudo docker restart <NAME OF HAPROXY ENTERPRISE CONTAINER>nixsudo docker restart <NAME OF HAPROXY ENTERPRISE CONTAINER>
Note that enabling mTLS in this way means that instead of authenticating with HAProxy Data Plane API using a username and password, you will use a client certificate and key.
You can test the HTTPS connection to 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
nix
outputjson
outputjson