Install the HAProxy Data Plane API on HAProxy

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.

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

On-demand webinar

HAProxy Data Plane API 101: Powering Interactions Across HAProxy

Run the API using systemd Jump to heading

Running the API as a systemd service enables you to issue CLI commands to a running haproxy process.

Download the latest 3.2.x package from the HAProxy Data Plane API GitHub repository. For Debian/Ubuntu, packages have the suffix .deb. For RHEL, packages have the suffix .rpm.

Install the package:

nix
sudo dpkg -i --force-depends dataplaneapi_3.2.5_linux_amd64.deb

nix
sudo dpkg -i --force-depends dataplaneapi_3.2.5_linux_amd64.deb

nix
sudo rpm -Uvh --nodeps dataplaneapi_3.2.5_linux_amd64.rpm

nix
sudo rpm -Uvh --nodeps dataplaneapi_3.2.5_linux_amd64.rpm

Ensure that your HAProxy configuration has a stats socket line in the global section.

This enables the Runtime API, which the Data Plane API uses to make some changes without requiring a reload.
```
haproxy.cfg
haproxy
global
  stats socket /var/run/haproxy.sock mode 660 level admin
```
```
haproxy.cfg
haproxy
global
  stats socket /var/run/haproxy.sock mode 660 level admin
```

Add a userlist section to the HAProxy configuration. This sets the authentication username to admin and password to adminpwd:

haproxy.cfg
haproxy
userlist dataplaneapi
  user admin insecure-password adminpwd

haproxy.cfg
haproxy
userlist dataplaneapi
  user admin insecure-password adminpwd

Start the Data Plane API:

nix
sudo systemctl start dataplaneapi

nix
sudo systemctl start dataplaneapi

Verify that the API is running properly by calling the info function:

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-08-23T15:38:09.000Z","version":"v3.2.5 1491b08a"},"system":{}}

output
json
{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.2.5 1491b08a"},"system":{}}

Run the API in Docker Jump to heading

Available since

HAProxy 2.0

The HAProxy Docker images come with the Data Plane API preinstalled. We recommend using the S6 Overlay versions, denoted with s6- prefix in the version name; an S6 initialization daemon process will separately start and manage HAProxy and the Data Plane API with the ability to auto-restart in case of a crash without impacting each other.

Create a directory on your workstation named haproxy to store your configuration files, and change directory into it.
```
nix
 mkdir haproxy
 cd haproxy
```
```
nix
 mkdir haproxy
 cd haproxy
```

Get a sample Data Plane API configuration file:

Download the latest 3.2.x archive from the HAProxy Data Plane API GitHub repository.

nix
wget https://github.com/haproxytech/dataplaneapi/releases/download/v3.2.5/dataplaneapi_3.2.5_linux_x86_64.tar.gz

nix
wget https://github.com/haproxytech/dataplaneapi/releases/download/v3.2.5/dataplaneapi_3.2.5_linux_x86_64.tar.gz

Extract the archive to get the sample configuration file dataplaneapi.yml.dist.

nix
tar -zxvf dataplaneapi_3.2.5_linux_x86_64.tar.gz

nix
tar -zxvf dataplaneapi_3.2.5_linux_x86_64.tar.gz

Rename the file dataplaneapi.yml.dist to dataplaneapi.yml.

nix
mv dataplaneapi.yml.dist dataplaneapi.yml

nix
mv dataplaneapi.yml.dist dataplaneapi.yml

Edit dataplaneapi.yml to change the file paths to the HAProxy configuration file and system binary. To send API logs to standard out, change the log_to line to stdout.

dataplaneapi.yml
yaml
haproxy:
  config_file: /usr/local/etc/haproxy/haproxy.cfg
  haproxy_bin: /usr/local/sbin/haproxy
log_targets:
- log_to: stdout

dataplaneapi.yml
yaml
haproxy:
  config_file: /usr/local/etc/haproxy/haproxy.cfg
  haproxy_bin: /usr/local/sbin/haproxy
log_targets:
- log_to: stdout

Create an HAProxy configuration file that has:
- a global section. The stats socket line enables the Runtime API, which the Data Plane API uses to make some changes without requiring a reload.
- a userlist section that sets the API authentication username and password. In the example below, we set the username to admin and password to your_pwd_here.
```
haproxy.cfg
haproxy
global
  stats socket /var/run/haproxy.sock mode 660 level admin
userlist dataplaneapi
  user admin insecure-password your_pwd_here
```
```
haproxy.cfg
haproxy
global
  stats socket /var/run/haproxy.sock mode 660 level admin
userlist dataplaneapi
  user admin insecure-password your_pwd_here
```

Run the Docker container, passing the -v flag to map your local haproxy directory to /usr/local/etc/haproxy inside the container.

Use an Ubuntu image.

nix
docker run \
  -d \
  --name my-running-haproxy \
  -p 5555:5555/tcp \
  -v ${PWD}:/usr/local/etc/haproxy:rw \
  haproxytech/haproxy-ubuntu:s6-latest

nix
docker run \
  -d \
  --name my-running-haproxy \
  -p 5555:5555/tcp \
  -v ${PWD}:/usr/local/etc/haproxy:rw \
  haproxytech/haproxy-ubuntu:s6-latest

Use a Debian image.

nix
docker run \
  -d \
  --name my-running-haproxy \
  -p 5555:5555/tcp \
  -v ${PWD}:/usr/local/etc/haproxy:rw \
  haproxytech/haproxy-debian:s6-latest

nix
docker run \
  -d \
  --name my-running-haproxy \
  -p 5555:5555/tcp \
  -v ${PWD}:/usr/local/etc/haproxy:rw \
  haproxytech/haproxy-debian:s6-latest

Use an Alpine image.

nix
docker run \
  -d \
  --name my-running-haproxy \
  -p 5555:5555/tcp \
  -v ${PWD}:/usr/local/etc/haproxy:rw \
  haproxytech/haproxy-alpine:s6-latest

nix
docker run \
  -d \
  --name my-running-haproxy \
  -p 5555:5555/tcp \
  -v ${PWD}:/usr/local/etc/haproxy:rw \
  haproxytech/haproxy-alpine:s6-latest

Verify that the API is running properly by calling the info function with the credentials from the HAProxy configuration file.

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

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

output
json
{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.2.5 1491b08a"},"system":{}}

output
json
{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.2.5 1491b08a"},"system":{}}

Troubleshooting Jump to heading

You get the error The configuration file isn't declared in the HAPROXY_CFGFILES environment variable, cannot start.

The value of config_file in your Data Plane API configuration must match the configuration file that HAProxy actually loaded. Try checking the value of the HAPROXY_CFGFILES environment variable by including it in your logs. Set your config_file field to match. For example, /usr/local/etc/haproxy/haproxy.cfg.
You get a permission denied error.

If you get an error like this:
```
json
{"code":500,"message":"dial unix /var/run/haproxy.sock: connect: permission denied"}
```
```
json
{"code":500,"message":"dial unix /var/run/haproxy.sock: connect: permission denied"}
```
This means that the user who runs the API doesn’t have access to the HAProxy socket. Check that you added them to the HAProxy group and log out and back in again.
You receive 400 Bad Request.

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

To enable HTTPS for Data Plane API with HAProxy, 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/haproxy/ssl/certs/server-cert.pem"
    tls_key: "/etc/haproxy/ssl/certs/server-key.pem"
  }
  ...
}

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

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

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

Set the following:

The scheme to https. 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 dataplaneapi

nix
sudo systemctl restart dataplaneapi

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

output
json
{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}

output
json
{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"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:

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/haproxy/ssl/certs/server-cert.pem"
    tls_key: "/etc/haproxy/ssl/certs/server-key.pem"
    tls_ca: "/etc/haproxy/ssl/certs/ca-cert.pem"
  }
  ...
}

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

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

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

Restart Data Plane API:

nix
sudo systemctl restart dataplaneapi

nix
sudo systemctl restart 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":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}

output
json
{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}

Product Documentation

API Documentation

Configuration Documentation

Install the HAProxy Data Plane API on HAProxy

Run the API using systemd Jump to heading

Run the API in Docker Jump to heading

Troubleshooting Jump to heading

Enable HTTPS Jump to heading

Enable mTLS Jump to heading

Product Documentation

API Documentation

Configuration Documentation

Run the API using systemd Jump to heading #

Run the API in Docker Jump to heading #

Troubleshooting Jump to heading #

Enable HTTPS Jump to heading #

Enable mTLS Jump to heading #

Privacy Settings

Run the API using systemd Jump to heading

Run the API in Docker Jump to heading

Troubleshooting Jump to heading

Enable HTTPS Jump to heading

Enable mTLS Jump to heading