Announcing HAProxy Data Plane API 2.6
Version Update

HAProxy Data Plane API 2.8 is now the latest version. Learn more

In HAProxy Data Plane API version 2.6, we continued the effort of expanding support for HAProxy configuration keywords, as this has been the priority with this release cycle, and it will be in the next one too to meet our goal of achieving complete feature parity with both the HAProxy configuration and Runtime API. This will enable you to use HAProxy Data Plane API for configuring HAProxy without any gaps in functionality.

With that in mind, we also implemented quality of life improvements, namely adding a health check endpoint that returns the status of the HAProxy process, and we upgraded to Go 1.18 and updated all dependencies that we are using so users can benefit from bug and security fixes.

Extended Keyword Support

We updated the HAProxy Data Plane API to cover more HAProxy configuration keywords, with the goal of making the API a full-fledged way to configure HAProxy. In this section, you’ll see everything we’ve added.

The ring section

Since HAProxy 2.2, you’ve had the ability to define a section called ring which creates a FIFO buffer in memory where you can store HAProxy’s logs temporarily before forwarded them to a remote syslog server. The benefit of using a ring buffer is that it allows you to forward log messages to a remote syslog server using TCP. A traditional log line in an HAProxy configuration forwards logs using the UDP protocol. Relaying logs using UDP avoids any slowdowns, since UDP is a connectionless protocol, but the downside is that there is no guarantee that every log message will arrive at the destination. UDP is fire and forget.

# Uses a UDP port
log local0

However, by defining a ring section you can buffer log messages and then communicate with a syslog server over a TCP port without slowing down HAProxy since the log forwarding happens in the background. The TCP protocol is a connected protocol and guarantees delivery of all messages. In the snippet below, we define a ring section for buffering HAProxy logs.

ring logbuffer
description "My log buffer"
format rfc3164
maxlen 1200
size 32764
timeout connect 5s
timeout server 10s
# Uses a TCP port
server mysyslogsrv log-proto octet-count

Then in the global section of your configuration, your log line would specify the ring buffer instead of an IP address and port:

log ring@logbuffer local0 info

You can now create a ring section through the API by using the /services/haproxy/configuration/rings endpoint, as shown below.

$ curl -X POST \
--user admin:password \
-H "Content-Type: application/json" \
-d '{
"name": "logbuffer",
"description": "My log buffer",
"format": "rfc3164",
"maxlen": 1200,
"size": 32764,
"timeout_connect": 5000,
"timeout_server": 1000
}' \

Then add a server to it by using the /services/haproxy/configuration/servers endpoint, setting the URL parameter parent_type to ring and parent_name to the name of the ring section.

$ curl -X POST \
-–user admin:password \
-H "Content-Type: application/json" \
-d '{
"name": "mysyslogsrv",
"address": "",
"port": 514,
"log_proto": "octet-count"
}' \

To remain backward compatible, the server endpoint will still have the backend query string parameter, but it will be removed in a future version. Going forward please use parenttype and parentname query string parameters to specify the section to which a server resource belongs.

Add the required log line to your global section by invoking the /services/haproxy/configuration/log_targets endpoint.

The log-forward section


An earlier version of this post recommended using the log-forward section for load balancing, but this has been amended to indicate that the use case is primarily log forwarding, since health checking is not yet available.

While the ring section pertains to forwarding HAProxy’s own logs, another section named log-forward pertains to forwarding log messages for other applications to a list of syslog servers. This gets its own section in order to support relaying syslog messages over UDP, while in general HAProxy is a TCP-based proxy. The log-forward section was introduced in HAProxy 2.3 and looks like this:

log-forward sylog
# receive log messages on UDP port
# receive log messages on TCP port
# forward to this syslog server using UDP
log local0

You can create a log-forward section through the API by using the new /services/haproxy/configuration/log_forwards endpoint.

$ curl -X POST \
-–user admin:password \
-H "Content-Type: application/json" \
-d '{
"name": "sylog",
"maxconn": 100
}' \

Then add a bind line for receiving syslog traffic over TCP and a dgram_bind line for receiving it over UDP by calling the /services/haproxy/configuration/binds and /services/haproxy/configuration/dgram_binds endpoints:

$ curl -X POST \
-–user admin:password \
-H "Content-Type: application/json" \
-d '{
"address": "",
"port": 514
}' \
$ curl -X POST \
-–user admin:password \
-H "Content-Type: application/json" \
-d '{
"address": "",
"port": 514
}' \

To remain backward compatible, the bind resource will still have the frontend query string parameter, but it will be removed in a future version. Going forward please use parenttype and parentname query string parameters to specify the section to which a bind resource belongs too.

Finally, add the log servers to which you will forward traffic by invoking the /services/haproxy/configuration/log_targets endpoint.

$ curl -X POST \
-–user admin:password \
-H "Content-Type: application/json" \
-d '{
"address": "",
"facility": "level0",
"sample_range": "1",
"sample_size": 2,
}' \

Global section keywords

With version 2.6, we’re happy to announce that the /services/haproxy/configuration/global endpoint supports all options for the HAProxy global section.

Process management and security:

  • default-path

  • description

  • expose-experimental-directives

  • gid

  • grace

  • insecure-fork-wanted

  • insecure-setuid-wanted

  • issuers-chain-path

  • h2-workaround-bogus-websocket-clients

  • log-tag

  • lua-load-per-thread

  • mworker-max-reloads

  • node

  • numa-cpu-mapping

  • pp2-never-send-local

  • presetenv

  • resetenv

  • uid

  • ulimit-n

  • set-dumpable

  • set-var

  • setenv

  • unix-bind

  • unsetenv

  • strict-limits

SSL tuning options:

  • ssl-default-bind-ciphers

  • ssl-default-bind-ciphersuites

  • ssl-default-bind-curves

  • ssl-default-bind-options

  • ssl-default-server-ciphers

  • ssl-default-server-ciphersuites

  • ssl-default-server-options

  • ssl-dh-param-file

  • ssl-server-verify

  • ssl-skip-self-issued-ca

Performance tuning:

  • busy-polling

  • max-spread-checks

  • maxconnrate

  • maxcomprate

  • maxcompcpuusage

  • maxpipes

  • maxsessrate

  • maxsslconn

  • maxsslrate

  • maxzlibmem

  • noepoll

  • nokqueue

  • noevports

  • nopoll

  • nosplice

  • nogetaddrinfo

  • noreuseport

  • profiling.tasks

  • spread-checks

  • ssl-engine

Defaults, frontend and backend keywords

Version 2.6 of the HAProxy Data Plane API also brings support or all option keywords that can be configured in defaultsbackend, and frontend sections via the /services/haproxy/configuration/defaults, /services/haproxy/configuration/frontends, and /services/haproxy/configuration/backends API endpoints:

  • option abortonclose

  • option checkcache

  • option http-ignore-probes

  • option http-no-delay

  • option http-use-proxy-header

  • option httpslog

  • option independent-streams

  • option nolinger

  • option originalto

  • option persist

  • option prefer-last-server

  • option socket-stats

  • option splice-auto

  • option splice-request

  • option splice-response

  • option spop-check

  • option srvtcpka

  • option tcp-smart-accept

  • option tcp-smart-connect

  • option tcpka

  • option transparent

In addition, we’ve extended the stats object that you can configure in a frontend or backend section to include the following options:

  • stats auth

  • stats http-request

  • stats realm

For the backend and the defaults sections we added support for the server TCP keep-alive options:

  • srvtcpka-cnt

  • srvtcpka-idle

  • Srvtcpka-intvl

For the frontend and the defaults sections we added support for the client TCP keep-alive options:

  • clitcpka-cnt

  • clitcpka-idle

  • clitcpka-intvl

The http-after-response directive

HAProxy 2.6 introduced the http-after-response directive, which applies an action to all responses, even those generated by HAProxy and returned without involving a backend server. People use it to attach HTTP headers to a response when HAProxy returns a redirect, for example. The older http-response directive applies only when the backend server sends the response.

With HAProxy Data Plane API 2.6, you can configure http-after-response directives similarly to how you would configure http-response directives, only using the /services/haproxy/configuration/httpafterresponse_rules endpoint.

$ curl -X POST \
-–user admin:password \
-H "Content-Type: application/json" \
-d '{
"index": 0,
"action": "set-header",
"hdr_name": "Cache-Control",
"hdr_fmt": "no-store,no-cache,private",
}' \

This will create the following line in your frontend section in the HAProxy configuration file:

frontend test
http-after-response set-header Cache-Control "no-store,no-cache,private"

Health Endpoint

A new endpoint, /health, returns a value indicating whether HAProxy is up and running.

$ curl -X GET \
-–user admin:password \
-H "Content-Type: application/json" \
HTTP/1.1 200 OK
Content-Type: application/json
Vary: Origin
Date: Thu, 14 Jul 2022 13:01:17 GMT
Content-Length: 22
Connection: close
"haproxy": "up"

To enable this feature, you must configure the status_cmd field in the HAProxy Data Plane API configuration file (e.g. /etc/haproxy/dataplaneapi.hcl), as shown below.


haproxy {
config_file = "/etc/haproxy/haproxy.cfg"
haproxy_bin = "haproxy"
reload {
reload_delay = 5
reload_cmd = "systemctl reload haproxy"
restart_cmd = "systemctl restart haproxy"
status_cmd = "systemctl status haproxy"
reload_retention = 1


config_file: "/etc/haproxy/haproxy.cfg"
haproxy_bin: "haproxy"
reload_delay: 5
reload_cmd: "systemctl reload haproxy"
restart_cmd: "systemctl restart haproxy"
status_cmd: "systemctl status haproxy"
reload_retention: 1

Library Updates and Bug Fixes

One of the bigger updates is that the HAProxy Data Plane API project has been migrated to Go 1.18 along with the underlying libraries config-parser and client-native. This allows us to get all the new features of the Go language to improve our codebase, along with some optimizations and, of course, security fixes.

We’ve also updated the go-swagger library we use for code generation to the latest version, which received many bug fixes but introduced some breaking changes for our models package in the client-native project. So, the client-native package has been upgraded to v4. This is important news for all of our contributors, since they will need to update their dev environments for both Go 1.18 and go-swagger 0.29.0.

In addition to that, we did a thorough pass of all the external dependencies used by the HAProxy Data Plane API project and updated those dependencies where needed to benefit from all the bug and security fixes.


We’d like to thank the code contributors who helped make this version possible!



Amel Husic


Andjelko Horvat


Andjelko Iharos


Dinko Korunic


Connor Edwards


Dario Tranchitella


Goran Galinec




Marko Juraga


Moemen Mhedhbi


Norwin Schnyder


Robert Maticevic


Seena Fallah


Zlatko Bratkovic


Subscribe to our blog. Get the latest release updates, tutorials, and deep-dives from HAProxy experts.