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