HAProxy Community

If you are using the community version of HAProxy, follow these steps to install the Data Plane API.

1. Download the Data Plane API binary from the GitHub repository.

2. Extract the binary with tar and set its permissions to executable with chmod:

   $ tar -zxvf dataplaneapi_2.2.0_Linux_x86_64.tar.gz
   $ chmod +x build/dataplaneapi

3. Copy the file to /usr/local/bin/:

   $ sudo cp build/dataplaneapi /usr/local/bin/

4. The Data Plane API requires that you enable Basic authentication, which means that any user invoking its methods must provide valid credentials. Usernames and passwords are stored in the HAProxy configuration file inside a userlist section.

   • Add a userlist section with a username and password to the configuration file /etc/haproxy/haproxy.cfg. In the example below, we add a user named dataplaneapi with the password mypassword:

     userlist haproxy-dataplaneapi
        user dataplaneapi insecure-password mypassword

   • 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 haproxy-dataplaneapi
        user dataplaneapi password $5$aVnIFECJ$2QYP64eTTXZ1grSjwwdoQxK/AP8kcOflEO1Q5fc.5aA

   • Reload HAProxy.

5. The Data Plane API needs access to the HAProxy Runtime API. To do this, update your HAProxy configuration file so that it has a stats socket line in the global section.

   • Add the stats socket directive if not already present:

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

   • If you test the API by running it as your non-root user, you can add your own username to the same group:

     $ sudo usermod -a -G haproxy $USER

     If you do this, make sure that you log out and back in again for the permissions to take effect.

6. Start the Data Plane API:

   $ sudo dataplaneapi \
      --host 127.0.0.1 \
      --port 5555 \
      --haproxy-bin /usr/sbin/haproxy \
      --config-file /etc/haproxy/haproxy.cfg  \
      --reload-delay 5 \
      --reload-cmd "service haproxy reload" \
      --restart-cmd "service haproxy restart" \
      --userlist haproxy-dataplaneapi \
      --transaction-dir /tmp/haproxy

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

   $ curl -X GET --user dataplaneapi:mypassword http://localhost:5555/v2/info
   
   {"api":{"build_date":"0001-01-01T00:00:00.000Z","version":"v2.2.0 68bd22b"},"system":{}}

   If you get this error:

   {"code":500,"message":"dial unix /var/run/haproxy.sock: connect: permission denied"}

   This means that the user who runs the API does not have access to the HAProxy socket. Check that you added them to the HAProxy group and log out and back in again.

Next up