Install the HAProxy Data Plane API on HAProxy Enterprise

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

Available packages Jump to heading #

The following packages are available:

Install the API as a service Jump to heading #

To enable the Data Plane API as a Systemd service:

1. Install the Data Plane API x86-64 package.

   apt yum zypper pkg

   nix
   sudo apt-get install hapee-extras-dataplaneapi30

   nix
   sudo apt-get install hapee-extras-dataplaneapi30

   nix
   sudo yum install hapee-extras-dataplaneapi30

   nix
   sudo yum install hapee-extras-dataplaneapi30

   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

2. 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.0/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.0/hapee-lb.sock user hapee-lb group hapee mode 660 level admin expose-fd listeners

3. Configure the Basic authentication credentials you’ll use to access the API. You can either:

   Option 1: Set 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 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"
     }
   }

   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

   Option 2: Set the username and password in the HAProxy Enterprise configuration file

   Add a userlist section named hapee-dataplaneapi to your configuration file, /etc/hapee-<VERSION>/hapee-lb.cfg, and set a username and password via the user directive.

   In the example below, we add a user named admin with the password adminpwd:

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

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

   Optional: If you prefer to encrypt the password first, use the mkpasswd command to do so. If mkpasswd is not present on your OS, it can be installed by downloading the whois package on most Linux distributions; on RedHat you may have to explicitly install it via sudo yum install mkpasswd.

   nix
   mkpasswd -m sha-256 adminpwd

   nix
   mkpasswd -m sha-256 adminpwd

   Then copy and paste the encrypted password into your configuration file:

   hapee-lb.cfg
   haproxy
   userlist hapee-dataplaneapi
     user admin password $5$aVnIFECJ$2QYP64eTTXZ1grSjwwdoQxK/AP8kcOflEO1Q5fc.5aA

   hapee-lb.cfg
   haproxy
   userlist hapee-dataplaneapi
     user admin password $5$aVnIFECJ$2QYP64eTTXZ1grSjwwdoQxK/AP8kcOflEO1Q5fc.5aA

   If you find that your credentials are not working, check the other configuration file. There may be a competing username and password there!

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

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

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

1. 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.0/hapee-lb.sock: connect: permission denied"}

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

   This often means that the user who runs the API does not 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 #

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:

1. 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.0/certs/server-cert.pem"
       tls_key: "/etc/hapee-3.0/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.0/certs/server-cert.pem"
       tls_key: "/etc/hapee-3.0/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.0/certs/server-cert.pem
       tls_key: /etc/hapee-3.0/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.0/certs/server-cert.pem
       tls_key: /etc/hapee-3.0/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.

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

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:

1. 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.0/certs/server-cert.pem"
       tls_key: "/etc/hapee-3.0/certs/server-key.pem"
       tls_ca: "/etc/hapee-3.0/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.0/certs/server-cert.pem"
       tls_key: "/etc/hapee-3.0/certs/server-key.pem"
       tls_ca: "/etc/hapee-3.0/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.0/certs/server-cert.pem
       tls_key: /etc/hapee-3.0/certs/server-key.pem
       tls_ca: /etc/hapee-3.0/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.0/certs/server-cert.pem
       tls_key: /etc/hapee-3.0/certs/server-key.pem
       tls_ca: /etc/hapee-3.0/certs/ca-cert.pem
     ...

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