HAProxy Enterprise Documentation 2.3r1

HAProxy Enterprise

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

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

    This adds the program here: /opt/hapee-extras/sbin/hapee-dataplaneapi.

  2. Add a userlist section to your configuration file, /etc/hapee-2.3/hapee-lb.cfg, that sets a username and password to require when calling API functions.

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

    userlist hapee-dataplaneapi
       user admin insecure-password adminpwd

    Optionally, first encrypt the password with the mkpasswd command from the whois package:

    $ sudo apt install -y whois
    $ mkpasswd -m sha-256 mypassword
    # encrypted password displayed

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

    userlist hapee-dataplaneapi
       user admin password $5$aVnIFECJ$2QYP64eTTXZ1grSjwwdoQxK/AP8kcOflEO1Q5fc.5aA
  3. Be sure that your 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.

       stats socket /var/run/hapee-2.3/hapee-lb.sock user hapee-lb group hapee mode 660 level admin expose-fd listeners
  4. Enable and start the service:

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

Choose a different IP address and port

By default, the API listens on all IP addresses at port 5555. You can change this by editing the file /etc/hapee-extras/dataplaneapi.hcl.

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

    dataplaneapi {
       host = ""
       port = 5557

    Alternatively, set the $HOST and $PORT environment variables.

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

    $ curl -X GET --user admin:adminpwd http://localhost:5555/v2/info
    {"api":{"build_date":"2020-11-10T14:37:06.000Z","version":"v2.1.0-ee6 30a03a6.dirty"},"system":{}}

    If you get this error:

    {"code":500,"message":"dial unix /var/run/hapee-2.3/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