HAProxy Enterprise Documentation 1.6r2
HAProxy Community
If you are using the community version of HAProxy, follow these steps to install the Data Plane API.
Download the Data Plane API binary from the GitHub repository.
-
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
-
Copy the file to /usr/local/bin/:
$ sudo cp build/dataplaneapi /usr/local/bin/
-
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.
-
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.
-
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
-
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.
Run the API with the HAProxy Process Manager
When using HAProxy 2.0 or later, you can use the HAProxy Process Manager to start the Data Plane API. The Process Manager adds a new section called program
to the HAProxy configuration, which you can use to start external programs when HAProxy starts.
The following configuration starts the Data Plane API when the HAProxy process is started. The no option start-on-reload
line avoids restarting the Data Plane API each time that HAProxy reloads.
-
Add a program
section to your HAProxy configuration:
program api
command dataplaneapi --host 0.0.0.0 --port 5555 --haproxy-bin /usr/sbin/haproxy --config-file /etc/haproxy/haproxy.cfg --reload-cmd "systemctl reload haproxy" --reload-delay 5 --userlist haproxy-dataplaneapi
no option start-on-reload
-
For this to work, you must run HAProxy in master-worker mode by adding the master-worker
directive to your global
section (or by adding the -W command-line argument). Then when you view the status of HAProxy, you'll see the new program running alongside the HAProxy worker processes.
$ sudo systemctl restart haproxy
$ sudo systemctl status haproxy
Main PID: 1274 (haproxy)
Tasks: 6
Memory: 5.5M
CPU: 2.838s
CGroup: /system.slice/haproxy.service
1274 /usr/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -sf 2768 -x /run/haproxy/admin.sock
2768 /usr/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -sf 2662 -x /run/haproxy/admin.sock
2830 /usr/local/bin/dataplane-api --host 0.0.0.0 --port 5555 -b /usr/local/sbin/haproxy -c /etc/haproxy/haproxy.cfg -d 5 -r systemctl reload haproxy -u controller
2831 /usr/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -sf 2768 -x /run/haproxy/admin.sock
-
If HAProxy runs inside a Docker container in master-worker
mode (which is the default), you can use the kill -SIGUSR2 [PID]
command for the --reload-cmd
argument, where PID is always 1, to reload only the HAProxy worker processes without terminating the container's main process.
program api
command /etc/haproxy/dataplaneapi --host 0.0.0.0 --port 5555 --haproxy-bin /usr/sbin/haproxy --config-file /etc/haproxy/haproxy.cfg --reload-cmd "kill -SIGUSR2 1" --reload-delay 5 --userlist haproxy-dataplaneapi
no option start-on-reload
Next up
CLI