HAProxy Enterprise Documentation 2.4r1

Install the HAProxy Enterprise Data Plane API

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

Run the API as a Systemd service

You can enable the Data Plane API as a Systemd service.

  1. Install the Data Plane API package:

    For Data Plane API version 2.7:

    $ # On Debian/Ubuntu
$ sudo apt-get install hapee-extras-dataplaneapi27
    $ # On CentOS/RedHat/Oracle/Photon OS
$ sudo yum install hapee-extras-dataplaneapi27
    $ # On SUSE
$ sudo zypper install hapee-extras-dataplaneapi27
    $ # On FreeBSD
$ sudo pkg install hapee-extras-dataplaneapi27

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

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

  3. To set the Basic authentication credentials used when accessing the API, you can either:

    • Option 1: Set the username and password in the Data Plane API configuration file, /etc/hapee-extras/dataplaneapi.hcl.

      1. Add a user block to the Data Plane API configuration file and set the password via its insecure and password fields:

        dataplaneapi {

  user "admin" {
    insecure = true
    password = "adminpwd"
  }
}

    • Option 2: Set the username and password in the HAProxy Enterprise configuration file, /etc/hapee-2.4/hapee-lb.cfg.

      1. Add a userlist section named hapee-dataplaneapi to your configuration file, /etc/hapee-2.4/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:

        userlist hapee-dataplaneapi
  user admin insecure-password adminpwd

      2. Optional: If you prefer to encrypt the password first, use the mkpasswd command from the whois package to do so:

        $ mkpasswd -m sha-256 adminpwd

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

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

  4. Enable and restart the service:

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

Set the listening IP address and port

By default, the Data Plane API listens at TCP port 5555. You can change the listening IP address and port by editing the file /etc/hapee-extras/dataplaneapi.hcl.

  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 {
   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 file /etc/default/hapee-extras-dataplaneapi, which the service reads on startup.

    This example changes the HOST and PORT environment variables in the Data Plane API Systemd configuration.

    $ sudo editor /etc/default/hapee-extras-dataplaneapi
    HOST=192.168.50.20
PORT=5557
SYSD_OPTIONS='-f /etc/hapee-extras/dataplaneapi.hcl'
SYSV_OPTIONS=(-f /etc/hapee-extras/dataplaneapi.hcl)

  2. Restart the service:

    $ sudo systemctl restart hapee-extras-dataplaneapi

Verify that the API works

  1. Verify that the API is running properly by calling the info API endpoint:

    $ curl -X GET --user admin:adminpwd http://localhost:5555/v2/info
    {"api":{"build_date":"2023-02-17T14:41:27.000Z","version":"v2.7.2-ee1 191e89da"},"system":{}}

    If you get this error:

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

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

Next up

CLI