Install the HAProxy Data Plane API on HAProxy Enterprise

This section describes how to install the HAProxy Data Plane API on HAProxy Enterprise.

HAProxy Data Plane API and HAProxy Fusion

If your load balancer is managed by HAProxy Fusion, use the HAProxy Fusion API instead of the Data Plane API. HAProxy Fusion installs and uses the Data Plane API on load balancer nodes that it manages. Don’t reinstall the 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.

Install the HAProxy Data Plane API as a service Jump to heading

To enable the Data Plane API as a Systemd service:

Install the Data Plane API x86-64 package.

Install the software

nix
sudo apt-get install hapee-extras-dataplaneapi32

nix
sudo apt-get install hapee-extras-dataplaneapi32

nix
sudo yum install hapee-extras-dataplaneapi32 --allowerasing

nix
sudo yum install hapee-extras-dataplaneapi32 --allowerasing

nix
sudo zypper install hapee-extras-dataplaneapi32

nix
sudo zypper install hapee-extras-dataplaneapi32

nix
sudo pkg install hapee-extras-dataplaneapi32

nix
sudo pkg install hapee-extras-dataplaneapi32

nix
sudo apt-get install hapee-extras-dataplaneapi31

nix
sudo apt-get install hapee-extras-dataplaneapi31

nix
sudo yum install hapee-extras-dataplaneapi31 --allowerasing

nix
sudo yum install hapee-extras-dataplaneapi31 --allowerasing

nix
sudo zypper install hapee-extras-dataplaneapi31

nix
sudo zypper install hapee-extras-dataplaneapi31

nix
sudo pkg install hapee-extras-dataplaneapi31

nix
sudo pkg install hapee-extras-dataplaneapi31

nix
sudo apt-get install hapee-extras-dataplaneapi30

nix
sudo apt-get install hapee-extras-dataplaneapi30

nix
sudo yum install hapee-extras-dataplaneapi30 --allowerasing

nix
sudo yum install hapee-extras-dataplaneapi30 --allowerasing

nix
sudo zypper install hapee-extras-dataplaneapi30

nix
sudo zypper install hapee-extras-dataplaneapi30

nix
sudo pkg install hapee-extras-dataplaneapi30

nix
sudo pkg install hapee-extras-dataplaneapi30

nix
sudo apt-get install hapee-extras-dataplaneapi29

nix
sudo apt-get install hapee-extras-dataplaneapi29

nix
sudo yum install hapee-extras-dataplaneapi29 --allowerasing

nix
sudo yum install hapee-extras-dataplaneapi29 --allowerasing

nix
sudo zypper install hapee-extras-dataplaneapi29

nix
sudo zypper install hapee-extras-dataplaneapi29

nix
sudo pkg install hapee-extras-dataplaneapi29

nix
sudo pkg install hapee-extras-dataplaneapi29

nix
sudo apt-get install hapee-extras-dataplaneapi28

nix
sudo apt-get install hapee-extras-dataplaneapi28

nix
sudo yum install hapee-extras-dataplaneapi28 --allowerasing

nix
sudo yum install hapee-extras-dataplaneapi28 --allowerasing

nix
sudo zypper install hapee-extras-dataplaneapi28

nix
sudo zypper install hapee-extras-dataplaneapi28

nix
sudo pkg install hapee-extras-dataplaneapi28

nix
sudo pkg install hapee-extras-dataplaneapi28

nix
sudo apt-get install hapee-extras-dataplaneapi27

nix
sudo apt-get install hapee-extras-dataplaneapi27

nix
sudo yum install hapee-extras-dataplaneapi27 --allowerasing

nix
sudo yum install hapee-extras-dataplaneapi27 --allowerasing

nix
sudo zypper install hapee-extras-dataplaneapi27

nix
sudo zypper install hapee-extras-dataplaneapi27

nix
sudo pkg install hapee-extras-dataplaneapi27

nix
sudo pkg install hapee-extras-dataplaneapi27

nix
sudo apt-get install hapee-extras-dataplaneapi26

nix
sudo apt-get install hapee-extras-dataplaneapi26

nix
sudo yum install hapee-extras-dataplaneapi26 --allowerasing

nix
sudo yum install hapee-extras-dataplaneapi26 --allowerasing

nix
sudo zypper install hapee-extras-dataplaneapi26

nix
sudo zypper install hapee-extras-dataplaneapi26

nix
sudo pkg install hapee-extras-dataplaneapi26

nix
sudo pkg install hapee-extras-dataplaneapi26

nix
sudo apt-get install hapee-extras-dataplaneapi25

nix
sudo apt-get install hapee-extras-dataplaneapi25

nix
sudo yum install hapee-extras-dataplaneapi25 --allowerasing

nix
sudo yum install hapee-extras-dataplaneapi25 --allowerasing

nix
sudo zypper install hapee-extras-dataplaneapi25

nix
sudo zypper install hapee-extras-dataplaneapi25

nix
sudo pkg install hapee-extras-dataplaneapi25

nix
sudo pkg install hapee-extras-dataplaneapi25

nix
sudo apt-get install hapee-extras-dataplaneapi24

nix
sudo apt-get install hapee-extras-dataplaneapi24

nix
sudo yum install hapee-extras-dataplaneapi24 --allowerasing

nix
sudo yum install hapee-extras-dataplaneapi24 --allowerasing

nix
sudo zypper install hapee-extras-dataplaneapi24

nix
sudo zypper install hapee-extras-dataplaneapi24

nix
sudo pkg install hapee-extras-dataplaneapi24

nix
sudo pkg install hapee-extras-dataplaneapi24

nix
sudo apt-get install hapee-extras-dataplaneapi

nix
sudo apt-get install hapee-extras-dataplaneapi

nix
sudo yum install hapee-extras-dataplaneapi --allowerasing

nix
sudo yum install hapee-extras-dataplaneapi --allowerasing

nix
sudo zypper install hapee-extras-dataplaneapi

nix
sudo zypper install hapee-extras-dataplaneapi

nix
sudo pkg install hapee-extras-dataplaneapi

nix
sudo pkg install hapee-extras-dataplaneapi

Ensure that your HAProxy Enterprise configuration has a stats socket line in the global section; this enables the HAProxy Runtime API. The Data Plane API integrates with the Runtime API to make some configuration changes without needing to reload the load balancer.

hapee-lb.cfg
haproxy
global
  stats socket /var/run/hapee-3.2/hapee-lb.sock user hapee-lb group hapee mode 660 level admin expose-fd listeners

hapee-lb.cfg
haproxy
global
  stats socket /var/run/hapee-3.2/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 Data Plane API configuration file. Add a user block to the Data Plane API configuration file, and set the password via its insecure and password fields.
HAProxy Enterprise versions beyond 2.7r1 will use the configuration file /etc/hapee-extras/dataplaneapi.yml.
```
dataplaneapi.yml
yaml
dataplaneapi:
  user:
  - name: admin
    insecure: true
    password: adminpwd
```
```
dataplaneapi.yml
yaml
dataplaneapi:
  user:
  - name: admin
    insecure: true
    password: adminpwd
```
HAProxy Enterprise version 2.7r1 and earlier use the configuration file /etc/hapee-extras/dataplaneapi.hcl.
```
dataplaneapi.hcl
hcl
dataplaneapi { 
  user "admin" {
    insecure = true
    password = "adminpwd"
  }
}
```
```
dataplaneapi.hcl
hcl
dataplaneapi { 
  user "admin" {
    insecure = true
    password = "adminpwd"
  }
}
```

Enable and restart the service:

nix
sudo systemctl enable hapee-extras-dataplaneapi
sudo systemctl restart hapee-extras-dataplaneapi

nix
sudo systemctl enable hapee-extras-dataplaneapi
sudo systemctl restart hapee-extras-dataplaneapi

Change the listening IP address and port Jump to heading

By default, the Data Plane API listens on all IP addresses at TCP port 5555. You can change the listening IP address and port by editing the Data Plane API configuration file.

Data Plane API version 2.7 and earlier use the configuration file /etc/hapee-extras/dataplaneapi.hcl.
Data Plane API version 2.8 and beyond will use the configuration file /etc/hapee-extras/dataplaneapi.yml.

Change the host and/or port fields in the dataplaneapi block.

This example changes the host to 192.168.50.20 and the port from its default of 5555 to 5557.
```
dataplaneapi.hcl
hcl
dataplaneapi {
  host = "192.168.50.20"
  port = 5557
```
```
dataplaneapi.hcl
hcl
dataplaneapi {
  host = "192.168.50.20"
  port = 5557
```
```
dataplaneapi.yml
yaml
dataplaneapi:
  host: 192.168.50.20
  port: 5557
```
```
dataplaneapi.yml
yaml
dataplaneapi:
  host: 192.168.50.20
  port: 5557
```
Alternatively, set the HOST and PORT environment variables. Because the API runs as a Systemd service, you would add those variables to the configuration file, which the service reads on startup:
- On Debian/Ubuntu, /etc/default/hapee-extras-dataplaneapi
- On Alma/Oracle/Red Hat/Rocky, /etc/sysconfig/hapee-extras-dataplaneapi
```
hapee-extras-dataplaneapi
ini
HOST=192.168.50.20
PORT=5557
```
```
hapee-extras-dataplaneapi
ini
HOST=192.168.50.20
PORT=5557
```

Restart the service:

nix
sudo systemctl restart hapee-extras-dataplaneapi

nix
sudo systemctl restart hapee-extras-dataplaneapi

Verify that the API works Jump to heading

To verify that the API is running properly:

Try calling the info API endpoint:

nix
curl -X GET --user admin:adminpwd http://localhost:5555/v3/info

nix
curl -X GET --user admin:adminpwd http://localhost:5555/v3/info

output
json
{"api":{"build_date":"2024-11-14T14:23:12.000Z","version":"v3.0.3-ee1 3b84e390"},"system":{}}

output
json
{"api":{"build_date":"2024-11-14T14:23:12.000Z","version":"v3.0.3-ee1 3b84e390"},"system":{}}

Tip

If you get a permission denied error:

output
json
{"code":500,"message":"dial unix /var/run/hapee-3.2/hapee-lb.sock: connect: permission denied"}

output
json
{"code":500,"message":"dial unix /var/run/hapee-3.2/hapee-lb.sock: connect: permission denied"}

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.

Tip

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
curl -k -X GET --user admin:adminpwd https://localhost:5555/v3/info

nix
curl -k -X GET --user admin:adminpwd https://localhost:5555/v3/info

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 Data Plane API with HAProxy Enterprise, you must add a tls section to your Data Plane API configuration file and set the scheme to https:

Add the following to your Data Plane API configuration file:

dataplaneapi.hcl
hcl
dataplaneapi {
  host = "0.0.0.0"
  port = 5555
  scheme = ["https"]
  ...
  tls {
    tls_port = 6443
    tls_certificate: "/etc/hapee-3.2/certs/server-cert.pem"
    tls_key: "/etc/hapee-3.2/certs/server-key.pem"
  }
  ...
}

dataplaneapi.hcl
hcl
dataplaneapi {
  host = "0.0.0.0"
  port = 5555
  scheme = ["https"]
  ...
  tls {
    tls_port = 6443
    tls_certificate: "/etc/hapee-3.2/certs/server-cert.pem"
    tls_key: "/etc/hapee-3.2/certs/server-key.pem"
  }
  ...
}

dataplaneapi.yml
yaml
dataplaneapi:
  host: 0.0.0.0
  port: 5555
  scheme:
  - https
  ...
  tls:
    tls_port: 6443
    tls_certificate: /etc/hapee-3.2/certs/server-cert.pem
    tls_key: /etc/hapee-3.2/certs/server-key.pem
  ...

dataplaneapi.yml
yaml
dataplaneapi:
  host: 0.0.0.0
  port: 5555
  scheme:
  - https
  ...
  tls:
    tls_port: 6443
    tls_certificate: /etc/hapee-3.2/certs/server-cert.pem
    tls_key: /etc/hapee-3.2/certs/server-key.pem
  ...

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.

Restart Data Plane API:

nix
sudo systemctl restart hapee-extras-dataplaneapi

nix
sudo systemctl restart hapee-extras-dataplaneapi

You can test the HTTPS connection to the Data Plane API using curl, providing your username and password that you defined in the user section 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

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 with 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:

Add this line to your 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/hapee-3.2/certs/server-cert.pem"
    tls_key: "/etc/hapee-3.2/certs/server-key.pem"
    tls_ca: "/etc/hapee-3.2/certs/ca-cert.pem"
  }
  ...
}

dataplaneapi.hcl
hcl
dataplaneapi {
  host = "0.0.0.0"
  port = 5555
  scheme = ["https"]
  ...
  tls {
    tls_port = 6443
    tls_certificate: "/etc/hapee-3.2/certs/server-cert.pem"
    tls_key: "/etc/hapee-3.2/certs/server-key.pem"
    tls_ca: "/etc/hapee-3.2/certs/ca-cert.pem"
  }
  ...
}

dataplaneapi.yml
yaml
dataplaneapi:
  host: 0.0.0.0
  port: 5555
  scheme:
  - https
  ...
  tls:
    tls_port: 6443
    tls_certificate: /etc/hapee-3.2/certs/server-cert.pem
    tls_key: /etc/hapee-3.2/certs/server-key.pem
    tls_ca: /etc/hapee-3.2/certs/ca-cert.pem
  ...

dataplaneapi.yml
yaml
dataplaneapi:
  host: 0.0.0.0
  port: 5555
  scheme:
  - https
  ...
  tls:
    tls_port: 6443
    tls_certificate: /etc/hapee-3.2/certs/server-cert.pem
    tls_key: /etc/hapee-3.2/certs/server-key.pem
    tls_ca: /etc/hapee-3.2/certs/ca-cert.pem
  ...

Restart Data Plane API:

nix
sudo systemctl restart hapee-extras-dataplaneapi

nix
sudo systemctl restart hapee-extras-dataplaneapi

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

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":{}}

Product Documentation

API Documentation

Configuration Documentation

Install the HAProxy Data Plane API on HAProxy Enterprise

Install the HAProxy Data Plane API as a service Jump to heading

Change the listening IP address and port Jump to heading

Verify that the API works Jump to heading

Enable HTTPS Jump to heading

Enable mTLS Jump to heading

Product Documentation

API Documentation

Configuration Documentation

Install the HAProxy Data Plane API as a service Jump to heading #

Change the listening IP address and port Jump to heading #

Verify that the API works Jump to heading #

Enable HTTPS Jump to heading #

Enable mTLS Jump to heading #

Privacy Settings

Install the HAProxy Data Plane API as a service Jump to heading

Change the listening IP address and port Jump to heading

Verify that the API works Jump to heading

Enable HTTPS Jump to heading

Enable mTLS Jump to heading