# Quickstart HAProxy Community Edition dataplaneAPI

**URL:** <https://discourse.haproxy.org/t/quickstart-haproxy-community-edition-dataplaneapi/9164>\
**Category:** Configuration Samples\
**Created:** [October 25, 2023, 6:45pm UTC](https://discourse.haproxy.org/t/quickstart-haproxy-community-edition-dataplaneapi/9164 "2023-10-25T18:45:11Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![randomguy](https://avatars.discourse-cdn.com/v4/letter/r/ba8739/32.png) [@randomguy](https://discourse.haproxy.org/u/randomguy)\
**Post date:** [October 25, 2023, 6:45pm UTC](https://discourse.haproxy.org/t/quickstart-haproxy-community-edition-dataplaneapi/9164/1 "2023-10-25T18:45:11Z")

</div>

This guide was written after starting up a brand new Ubuntu Server on 22.04 and details the steps taken to quickly get the dataplaneapi up and running.

```auto
sudo apt-get update
sudo apt-get install haproxy

```

Run this to see what version is installed

```auto
haproxy -v 

```

For the sake of this discussion I have HAProxy 2.4.22

Running uname -a or uname -m told me I have x86\_64 - That is amd64 architecture

Pick the package that you need from this page:

> **[Release HAProxy Data Plane API v2.8.3 · haproxytech/dataplaneapi](https://github.com/haproxytech/dataplaneapi/releases/tag/v2.8.3)**
>
> Release Notes
> HAProxy Data Plane API v2.8.3 efa147f
> Build from: git@github.com:haproxytech/dataplaneapi.git
> Build date: 2023-10-11T15:31:41Z
> Changelog
> 
> c0f4bea BUILD/MINOR: github: add manual relea...

Note: API just needs to be a newer version than your haproxy version long as you are on HAProxy 1.9 and above.

I’m using this one: dataplaneapi\_2.8.3\_linux\_amd64.deb

Right click on the name and click copy link  
[https://github.com/haproxytech/dataplaneapi/releases/download/v2.8.3/dataplaneapi\_2.8.3\_linux\_amd64.deb](https://github.com/haproxytech/dataplaneapi/releases/download/v2.8.3/dataplaneapi_2.8.3_linux_amd64.deb)

Curl and download the file into your home directory:

```auto
cd ~
curl -JLO https://github.com/haproxytech/dataplaneapi/releases/download/v2.8.3/dataplaneapi_2.8.3_linux_amd64.deb

```

Install it:

```auto
sudo dpkg -i dataplaneapi_2.8.3_linux_amd64.deb

```

I can see that the dataplane api is now installed:

```auto
which dataplaneapi

```

Returns:

```auto
/usr/sbin/dataplaneapi

```

Make sure that the global configuration has the socket configured:

```auto
grep "global\|defaults\|stats socket" /etc/haproxy/haproxy.cfg

```

It should return this or something similar. If “defaults” shows before the stats line then you need to  
make sure you move the stats line under the global section

```auto
grep "global\|defaults\|stats socket" /etc/haproxy/haproxy.cfg

```

Returns:

```auto
global
        stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
defaults
        log global

```

Create the /etc/haproxy/dataplaneapi.yml file

```auto
sudo vi /etc/haproxy/dataplaneapi.yml

```

Paste the configuration from this page on step 5 - change the password as desired:

> **[Install the HAProxy Data Plane API on HAProxy](https://www.haproxy.com/documentation/haproxy-data-plane-api/installation/install-on-haproxy/)**
>
> This section describes how to install the HAProxy Data Plane API on HAProxy.

If you run this command to start it up it merely runs the API and starts the socket.  
It will appear to hang but that’s just because it’s listening. You can open another ssh session to test it.

```auto
sudo dataplaneapi -f /etc/haproxy/dataplaneapi.yml

```

Testing the api:  
With the above command running run this:

```auto
curl -X GET --user admin:adminpwd http://localhost:5555/v2/info

```

Result should be similar to this:

```auto
{"api":{"build_date":"2023-06-15T09:07:18.000Z","version":"v2.8.0 b77adc7"},"system":{}}

```

If it’s not then see the green “Tip” sections for help on this page:

> **[Install the HAProxy Data Plane API on HAProxy](https://www.haproxy.com/documentation/haproxy-data-plane-api/installation/install-on-haproxy/)**
>
> This section describes how to install the HAProxy Data Plane API on HAProxy.

Let’s make it load on startup

```auto
sudo vi /etc/haproxy/haproxy.cfg

```

Add these items in (note: the word ‘global’ should already be present, don’t duplicate it):

```auto
global
  master-worker
program api
  command dataplaneapi -f /etc/haproxy/dataplaneapi.yml
  no option start-on-reload

```

Restart haproxy:

```auto
sudo systemctl restart haproxy

```

This is my current frontend and backend configuration:

```auto
frontend frontend1
        bind *:80
        mode http
        option httplog
        log global

        default_backend be_app

backend be_app
        mode http
        option httpchk HEAD /
        log global
        server app1 172.16.1.32:80 cookie a1 check

```

If I query for the frontend this way:

```auto
curl -X GET --user admin:adminpwd "http://127.0.0.1:5555/v2/services/haproxy/configuration/frontends"

```

The response looks like this:

```auto
{"_version":2,"data":[{"default_backend":"be_app","from":"unnamed_defaults_1","httplog":true,"mode":"http","name":"frontend1"}]}

```

Personally that’s hard to read so I want to install jq and pipe the command to that so it reads like this:

```auto
sudo apt-get install jq

```

Now send it:

```auto
curl -X GET --user admin:adminpwd http://127.0.0.1:5555/v2/services/haproxy/configuration/frontends" | jq

```

Response is this:

```auto
  % Total % Received % Xferd Average Speed Time Time Time Current
                                 Dload Upload Total Spent Left Speed
100 129 100 129 0 0 262k 0 --:--:-- --:--:-- --:--:-- 125k
{
  "_version": 2,
  "data": [
    {
      "default_backend": "be_app",
      "from": "unnamed_defaults_1",
      "httplog": true,
      "mode": "http",
      "name": "frontend1"
    }
  ]
}	

```

---

<div class="post-metadata">

**Author:** ![Yosu\_Cadilla](https://sea2.discourse-cdn.com/flex016/user_avatar/discourse.haproxy.org/yosu_cadilla/32/1310_2.png) [@Yosu\_Cadilla](https://discourse.haproxy.org/u/Yosu_Cadilla)\
**Post date:** [October 25, 2023, 7:33pm UTC](https://discourse.haproxy.org/t/quickstart-haproxy-community-edition-dataplaneapi/9164/2 "2023-10-25T19:33:34Z")

</div>

Amazing guide @randomguy  
No wonder I was previously unable to make it work on my own, it’s quite involved!

---

<div class="post-metadata">

**Author:** ![Yosu\_Cadilla](https://sea2.discourse-cdn.com/flex016/user_avatar/discourse.haproxy.org/yosu_cadilla/32/1310_2.png) [@Yosu\_Cadilla](https://discourse.haproxy.org/u/Yosu_Cadilla)\
**Post date:** [October 25, 2023, 8:09pm UTC](https://discourse.haproxy.org/t/quickstart-haproxy-community-edition-dataplaneapi/9164/4 "2023-10-25T20:09:44Z")

</div>

```auto
{
   "_version": 4,
   "data": [
      {
         "default_backend": "be_app",
         "from": "RandomGuyRocks",
         "httplog": true,
         "mode": "http",
         "name": "Glorious"
      }
   ]
}

```

---

<div class="post-metadata">

**Author:** ![randomguy](https://avatars.discourse-cdn.com/v4/letter/r/ba8739/32.png) [@randomguy](https://discourse.haproxy.org/u/randomguy)\
**Post date:** [October 25, 2023, 8:30pm UTC](https://discourse.haproxy.org/t/quickstart-haproxy-community-edition-dataplaneapi/9164/5 "2023-10-25T20:30:01Z")

</div>

For any future readers there’s some good examples on using it here:

> **[Manage frontends](https://www.haproxy.com/documentation/haproxy-data-plane-api/tutorials/frontends/)**
>
> Accept incoming connections and forward them to defined backends.

Something to watch for is notice that a frontend configuration and a bind configuration are two different things so make sure you create both as needed.

---

<div class="post-metadata">

**Author:** ![Yosu\_Cadilla](https://sea2.discourse-cdn.com/flex016/user_avatar/discourse.haproxy.org/yosu_cadilla/32/1310_2.png) [@Yosu\_Cadilla](https://discourse.haproxy.org/u/Yosu_Cadilla)\
**Post date:** [January 11, 2024, 12:15pm UTC](https://discourse.haproxy.org/t/quickstart-haproxy-community-edition-dataplaneapi/9164/6 "2024-01-11T12:15:35Z")

</div>

Hi @randomguy Nate, any chance you could add to the guide these topics?:

- Creating a server
- Adding a server to a backend
- How to get the “version”

Thank you.

---

<div class="post-metadata">

**Author:** ![randomguy](https://avatars.discourse-cdn.com/v4/letter/r/ba8739/32.png) [@randomguy](https://discourse.haproxy.org/u/randomguy)\
**Post date:** [January 11, 2024, 4:43pm UTC](https://discourse.haproxy.org/t/quickstart-haproxy-community-edition-dataplaneapi/9164/7 "2024-01-11T16:43:51Z")

</div>

Just to be clear are you looking for the dataplane api version or the HAProxy version?

---

<div class="post-metadata">

**Author:** ![randomguy](https://avatars.discourse-cdn.com/v4/letter/r/ba8739/32.png) [@randomguy](https://discourse.haproxy.org/u/randomguy)\
**Post date:** [January 11, 2024, 6:32pm UTC](https://discourse.haproxy.org/t/quickstart-haproxy-community-edition-dataplaneapi/9164/8 "2024-01-11T18:32:29Z")

</div>

Hi @Yosu_Cadilla the way I commonly work through API stuff is to configure the object by hand and then run a call to the API to get the data and see what it looks like. Once I have a base structure understanding then the manuals and reference become helpful. I am NOT a programmer or the best person for this but this is how I do it.

For example

```auto
admin@HAProxy:~$ curl -k -X GET --user admin:adminpwd "https://172.16.1.2:5555/v2/services/haproxy/configuration" | jq -M . | grep -i server
  % Total % Received % Xferd Average Speed Time Time Time Current
                                 Dload Upload Total Spent Left Speed
100 8257 0 8257 0 0 719k 0 --:--:-- --:--:-- --:--:-- 733k
    "description": "Returns an array of all servers that are configured in specified backend.",
    "title": "Return an array of servers",
    "url": "/services/haproxy/configuration/servers"
    "description": "Returns an array of all configured nameservers.",
    "title": "Return an array of nameservers",
    "url": "/services/haproxy/configuration/nameservers"
    "description": "Returns an array of all server templates that are configured in specified backend.",
    "title": "Return an array of server templates",
    "url": "/services/haproxy/configuration/server_templates"
    "title": "Return an array of all Server Switching Rules",
    "url": "/services/haproxy/configuration/server_switching_rules"

```

From this I can see that I want servers

```auto
admin@HAProxy:~$ curl -k -X GET --user admin:adminpwd "https://172.16.1.2:5555/v2/services/haproxy/configuration/servers?parent_type=backend&parent_name=be_http" | jq -M .
  % Total % Received % Xferd Average Speed Time Time Time Current
                                 Dload Upload Total Spent Left Speed
100 79 100 79 0 0 11570 0 --:--:-- --:--:-- --:--:-- 13166
{
  "_version": 16,
  "data": [
    {
      "address": "172.16.1.32",
      "name": "server_1",
      "port": 80
    }
  ]
}

```

To reverse the process I just pull up the docs - [HAProxy Data Plane API](https://www.haproxy.com/documentation/dataplaneapi/community/#post-/services/haproxy/configuration/servers)

There’s an “example” tab so I can just take that and send it (or use my data from above).

```auto
admin@HAProxy:~$ curl -k -X POST \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -d '{
      "address": "172.16.1.33",
      "name": "server_2",
      "port": 80
    }' \
  "https://172.16.1.2:5555/v2/services/haproxy/configuration/servers?backend=be_http"
{"code":400,"message":"13: version or transaction not specified, specify only one"}

```

Notice that I changed from using ?parent\_type=backend&parent\_name=be\_http to just ?backend=be\_http. That’s just to illustrate the differences. That post should do the trick of creating a server and assigning it.

Oh but look I got an error! So check the reference doc and you’ll see “QUERY-STRING PARAMETERS” at the top. Notice that version is an option:

```auto
admin@HAProxy:~$ curl -k -X POST --user admin:adminpwd -H "Content-Type: application/json" -d '{
      "address": "172.16.1.33",
      "name": "server_2",
      "port": 80
    }' "https://172.16.1.2:5555/v2/services/haproxy/configuration/servers?backend=be_http&version=1"
{"code":409,"message":"15: version in configuration file is 16, given version is 1"}

```

I just tagged that variable “version” on the end and dang another error but fairly clear. A quick adjustment to the version string and I’m all set.

```auto
admin@HAProxy:~$ curl -k -X POST --user admin:adminpwd -H "Content-Type: application/json" -d '{
      "address": "172.16.1.33",
      "name": "server_2",
      "port": 80
    }' "https://172.16.1.2:5555/v2/services/haproxy/configuration/servers?backend=be_http&version=16"
{"address":"172.16.1.33","name":"server_2","port":80}

```

My config file now has this (I cut a few lines just to make it easier to read). So it created the server and assigned it.

```auto
backend be_http from unnamed_defaults_1
  server server_1 172.16.1.32:80
  server server_2 172.16.1.33:80

```

That’s how you can walk through the API and also use the reference to find what you need. I did a search for “version” and nothing showed up in the docs so I just jump on down to the root and start working through it:

```auto
admin@HAProxy:~$ curl -k -X GET --user admin:adminpwd "https://172.16.1.2:5555/v2/" | jq -M .
  % Total % Received % Xferd Average Speed Time Time Time Current
                                 Dload Upload Total Spent Left Speed
100 1259 100 1259 0 0 110k 0 --:--:-- --:--:-- --:--:-- 111k
[
  {
    "description": "Return API, hardware and OS information",
    "title": "Return API, hardware and OS information",
    "url": "/info"
  },
  ...snip...

```

Ah that looks promising

```auto
admin@HAProxy:~$ curl -k -X GET --user admin:adminpwd "https://172.16.1.2:5555/v2/info" | jq -M
.
  % Total % Received % Xferd Average Speed Time Time Time Current
                                 Dload Upload Total Spent Left Speed
100 94 100 94 0 0 13599 0 --:--:-- --:--:-- --:--:-- 15666
{
  "api": {
    "build_date": "2024-01-02T12:00:36.000Z",
    "version": "v2.8.4-ee3 8182e868"
  },
  "system": {}
}

```

There’s a ton more to explore and play with but hopefully this gives you some insight into how you can leverage the docs and the API.

---

<div class="post-metadata">

**Author:** ![Yosu\_Cadilla](https://sea2.discourse-cdn.com/flex016/user_avatar/discourse.haproxy.org/yosu_cadilla/32/1310_2.png) [@Yosu\_Cadilla](https://discourse.haproxy.org/u/Yosu_Cadilla)\
**Post date:** [January 11, 2024, 7:22pm UTC](https://discourse.haproxy.org/t/quickstart-haproxy-community-edition-dataplaneapi/9164/9 "2024-01-11T19:22:01Z")

</div>

> [@randomguy](#):
>
> There’s an “example” tab so I can just take that and send it (or use my data from above).
> 
> ``

Reverse engineering the HAPDPAPI!  
It’s a good way to “build” the json indeed.  
Thanks !

---

<div class="post-metadata">

**Author:** ![sithlord](https://avatars.discourse-cdn.com/v4/letter/s/d78d45/32.png) [@sithlord](https://discourse.haproxy.org/u/sithlord)\
**Post date:** [January 20, 2024, 11:34am UTC](https://discourse.haproxy.org/t/quickstart-haproxy-community-edition-dataplaneapi/9164/10 "2024-01-20T11:34:22Z")

</div>

@Yosu_Cadilla Why not use one of the available Terraform providers to configure HAProxy, works like a charm fairly well-documented and simple to use [Terraform Registry](https://registry.terraform.io/providers/SepehrImanian/haproxy/latest/docs)