Installation

Install the HAProxy Data Plane API on HAProxy

On this page

Version 3.0 contains breaking changes

If you’re installing HAProxy Data Plane API 3.x, know that it changes several conventions that were present in version 2.x, and that upgrading to 3.x will require you to call the API endpoints differently. See the release notes for more details.

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

Run the API in the current terminal session Jump to heading

You can run the API in your current terminal session by following these steps on the HAProxy server. When you are finished with the API, stop it with Ctrl + C.

  1. Download the latest 3.0.x archive from the HAProxy Data Plane API GitHub repository.

    nix
    wget https://github.com/haproxytech/dataplaneapi/releases/download/v3.0.3/dataplaneapi_3.0.3_linux_x86_64.tar.gz
    nix
    wget https://github.com/haproxytech/dataplaneapi/releases/download/v3.0.3/dataplaneapi_3.0.3_linux_x86_64.tar.gz

  2. Extract the archive and set the permissions on the dataplaneapi program to executable with chmod:

    nix
    tar -zxvf dataplaneapi_3.0.3_linux_x86_64.tar.gz
    chmod +x dataplaneapi
    nix
    tar -zxvf dataplaneapi_3.0.3_linux_x86_64.tar.gz
    chmod +x dataplaneapi

  3. Copy the dataplaneapi program to /usr/local/bin/:

    nix
    sudo cp dataplaneapi /usr/local/bin/
    nix
    sudo cp dataplaneapi /usr/local/bin/

  4. Copy the Data Plane API configuration file to /etc/haproxy/dataplaneapi.yml:

    nix
    sudo cp dataplaneapi.yml.dist /etc/haproxy/dataplaneapi.yml 
    nix
    sudo cp dataplaneapi.yml.dist /etc/haproxy/dataplaneapi.yml

  5. Ensure that your HAProxy 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.

    haproxy.cfg
    haproxy
    global
      stats socket /var/run/haproxy.sock mode 660 level admin
    haproxy.cfg
    haproxy
    global
      stats socket /var/run/haproxy.sock mode 660 level admin

  6. Add a userlist section to the HAProxy configuration. This sets the authentication username to admin and password to adminpwd:

    haproxy.cfg
    haproxy
    userlist dataplaneapi
      user admin insecure-password adminpwd
    haproxy.cfg
    haproxy
    userlist dataplaneapi
      user admin insecure-password adminpwd

  7. Start the Data Plane API:

    nix
    sudo dataplaneapi -f /etc/haproxy/dataplaneapi.yml
    nix
    sudo dataplaneapi -f /etc/haproxy/dataplaneapi.yml

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

    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-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}
    output
    json
    {"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}

Run the API with the HAProxy Process Manager Jump to heading

Available since

  • HAProxy 2.0

You can use the HAProxy Process Manager to run the Data Plane API as a background service. The Process Manager requires a section called program in your HAProxy configuration, which you can use to start the Data Plane API program when HAProxy starts. Follow these steps on the HAProxy server:

  1. Download the latest 3.0.x archive from the HAProxy Data Plane API GitHub repository.

    nix
    wget https://github.com/haproxytech/dataplaneapi/releases/download/v3.0.3/dataplaneapi_3.0.3_linux_x86_64.tar.gz
    nix
    wget https://github.com/haproxytech/dataplaneapi/releases/download/v3.0.3/dataplaneapi_3.0.3_linux_x86_64.tar.gz

  2. Extract the archive and set the permissions on the dataplaneapi program to executable with chmod:

    nix
    tar -zxvf dataplaneapi_3.0.3_linux_x86_64.tar.gz
    chmod +x dataplaneapi
    nix
    tar -zxvf dataplaneapi_3.0.3_linux_x86_64.tar.gz
    chmod +x dataplaneapi

  3. Copy the dataplaneapi program to /usr/local/bin/:

    nix
    sudo cp dataplaneapi /usr/local/bin/
    nix
    sudo cp dataplaneapi /usr/local/bin/

  4. Copy the Data Plane API configuration file to /etc/haproxy/dataplaneapi.yml:

    nix
    sudo cp dataplaneapi.yml.dist /etc/haproxy/dataplaneapi.yml 
    nix
    sudo cp dataplaneapi.yml.dist /etc/haproxy/dataplaneapi.yml

  5. Ensure that your HAProxy configuration has:

    • a global section. The stats socket line enables the Runtime API, which the Data Plane API uses to make some changes without requiring a reload. The master-worker and insecure-fork-wanted lines are required to use the program section.
    • a userlist section. The user line sets the username and password you’ll use to access the API. In the example below, we set the username to admin and password to adminpwd.
    • a program section. The command line runs the Data Plane API.
    haproxy.cfg
    haproxy
    global
      stats socket /var/run/haproxy.sock mode 660 level admin
      master-worker
      insecure-fork-wanted
    userlist dataplaneapi
      user admin insecure-password adminpwd
    program api
      command /usr/local/bin/dataplaneapi -f /etc/haproxy/dataplaneapi.yml
      no option start-on-reload
    haproxy.cfg
    haproxy
    global
      stats socket /var/run/haproxy.sock mode 660 level admin
      master-worker
      insecure-fork-wanted
    userlist dataplaneapi
      user admin insecure-password adminpwd
    program api
      command /usr/local/bin/dataplaneapi -f /etc/haproxy/dataplaneapi.yml
      no option start-on-reload

  6. Then when you restart HAProxy and view its status, you’ll see the new program running alongside the HAProxy worker processes.

    nix
    sudo systemctl restart haproxy
    sudo systemctl status haproxy
    nix
    sudo systemctl restart haproxy
    sudo systemctl status haproxy
    output
    text
    haproxy.service - HAProxy Load Balancer
      Loaded: loaded (/etc/systemd/system/haproxy.service; enabled; vendor preset: enabled)
      Active: active (running) since Fri 2024-08-30 21:47:18 UTC; 8min ago
    Main PID: 40359 (haproxy)
      Status: "Ready."
       Tasks: 11 (limit: 510)
      Memory: 99.6M
         CPU: 2.696s
      CGroup: /system.slice/haproxy.service
              ├─40359 /usr/local/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -S /run/haproxy-master.sock
              ├─40361 dataplaneapi -f /etc/haproxy/dataplaneapi.yml
              └─40362 /usr/local/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -S /run/haproxy-master.sock
    output
    text
    haproxy.service - HAProxy Load Balancer
      Loaded: loaded (/etc/systemd/system/haproxy.service; enabled; vendor preset: enabled)
      Active: active (running) since Fri 2024-08-30 21:47:18 UTC; 8min ago
    Main PID: 40359 (haproxy)
      Status: "Ready."
       Tasks: 11 (limit: 510)
      Memory: 99.6M
         CPU: 2.696s
      CGroup: /system.slice/haproxy.service
              ├─40359 /usr/local/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -S /run/haproxy-master.sock
              ├─40361 dataplaneapi -f /etc/haproxy/dataplaneapi.yml
              └─40362 /usr/local/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -S /run/haproxy-master.sock

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

    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-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}
    output
    json
    {"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}

Run the API in Docker Jump to heading

Available since

  • HAProxy 2.0

The HAProxy Docker images come with the Data Plane API preinstalled. You can then add a program section to run it in the background.

  1. Create a folder on your workstation named haproxy. Here, you will keep your configuration files.

  2. To get a sample Data Plane API configuration file:

    • Download the latest 3.0.x archive from the HAProxy Data Plane API GitHub repository.

      nix
      wget https://github.com/haproxytech/dataplaneapi/releases/download/v3.0.3/dataplaneapi_3.0.3_linux_x86_64.tar.gz
      nix
      wget https://github.com/haproxytech/dataplaneapi/releases/download/v3.0.3/dataplaneapi_3.0.3_linux_x86_64.tar.gz

    • Extract the archive to get the sample configuration file dataplaneapi.yml.dist.

      nix
      tar -zxvf dataplaneapi_3.0.3_linux_x86_64.tar.gz
      nix
      tar -zxvf dataplaneapi_3.0.3_linux_x86_64.tar.gz

    • Rename the file dataplaneapi.yml.dist to dataplaneapi.yml and move it into your haproxy folder.

    • Change the file paths to the HAProxy program and configuration file:

      dataplaneapi.yml
      yaml
      haproxy:
        config_file: /usr/local/etc/haproxy/haproxy.cfg
        haproxy_bin: /usr/local/sbin/haproxy
      dataplaneapi.yml
      yaml
      haproxy:
        config_file: /usr/local/etc/haproxy/haproxy.cfg
        haproxy_bin: /usr/local/sbin/haproxy

    • To send API logs to standard out, change the log_to line to stdout:

      dataplaneapi.yml
      yaml
      log_targets:
      - log_to: stdout
      dataplaneapi.yml
      yaml
      log_targets:
      - log_to: stdout

  3. Create an HAProxy configuration file that has:

    • a global section. The stats socket line enables the Runtime API, which the Data Plane API uses to make some changes without requiring a reload. The master-worker and insecure-fork-wanted lines are required to use the program section.
    • a userlist section that sets the API authentication username and password. In the example below, we set the username to admin and password to adminpwd.
    • a program section to run the Data Plane API. The command will indicate the path to the Data Plane API program. Use /usr/local/bin/dataplaneapi for HAProxy Data Plane API version 3.0, or /usr/local/bin/dataplaneapi-v2 for version 2.0.
    haproxy.cfg
    haproxy
    global
      stats socket /var/run/haproxy.sock mode 660 level admin
      master-worker
      insecure-fork-wanted
    userlist dataplaneapi
      user admin insecure-password adminpwd
    program api
      command /usr/local/bin/dataplaneapi -f /etc/haproxy/dataplaneapi.yml
      no option start-on-reload
    haproxy.cfg
    haproxy
    global
      stats socket /var/run/haproxy.sock mode 660 level admin
      master-worker
      insecure-fork-wanted
    userlist dataplaneapi
      user admin insecure-password adminpwd
    program api
      command /usr/local/bin/dataplaneapi -f /etc/haproxy/dataplaneapi.yml
      no option start-on-reload

  4. Change directory into the haproxy folder. Then run the Docker container, passing the -v flag to map your local haproxy folder to /usr/local/etc/haproxy inside the container:

    nix
    docker run -d --name my-running-haproxy -p 5555:5555/tcp -v  ${PWD}:/usr/local/etc/haproxy:rw haproxytech/haproxy-ubuntu
    nix
    docker run -d --name my-running-haproxy -p 5555:5555/tcp -v  ${PWD}:/usr/local/etc/haproxy:rw haproxytech/haproxy-ubuntu

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

    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-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}
    output
    json
    {"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}

Troubleshooting Jump to heading

  • You get the error The configuration file is not declared in the HAPROXY_CFGFILES environment variable, cannot start.

    The value of config_file in your Data Plane API configuration must match the configuration file that HAProxy actually loaded. Try checking the value of the HAPROXY_CFGFILES environment variable by including it in your logs. Set your config_file field to match. For example, /usr/local/etc/haproxy/haproxy.cfg.

  • You get a permission denied error.

    If you get an error like this:

    json
    {"code":500,"message":"dial unix /var/run/haproxy.sock: connect: permission denied"}
    json
    {"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.

  • You receive 400 Bad Request.

    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

Do you have any suggestions on how we can improve the content of this page?

Previous page Installation Next page Install on HAProxy Enterprise
© 2024 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences