HAProxy Data Plane API Configuration

June 27, 2026 · View on GitHub

Overview

The primary configuration for the Data Plane API is managed through a YAML file. This file allows you to set various parameters that control the behavior of the API and its interaction with HAProxy.

Top-Level Configuration Options

Option	Type	Required	Description
`config_version`	integer	No	Configuration version
`name`	string	No	Name

Structure

The configuration file is structured into several sections, each corresponding to a different aspect of the Data Plane API's functionality. Here's a breakdown of the main sections and their options:

dataplaneapi Configuration Options

Option	Type	Required	Description
`write_timeout`	string	No	Specifies the write timeout for API requests
`graceful_timeout`	string	No	Sets the graceful shutdown timeout
`show_system_info`	boolean	No	Enables or disables the display of system information on the info endpoint
`max_header_size`	string	No	Defines the maximum header size for API requests
`max_body_size`	string	No	Defines the maximum request body size the API will read; 0 means unlimited (defaults to 1GiB)
`socket_path`	string	No	Specifies the path to the API's Unix socket
`debug_socket_path`	string	No	Defines the path for the debugging command socket
`host`	string	No	Sets the host address for the API
`port`	integer	No	Defines the port number for the API
`listen_limit`	integer	No	Sets the maximum number of connections the API can handle
`disable_inotify`	boolean	No	Disables the inotify watcher for the configuration file
`read_timeout`	string	No	Specifies the read timeout for API requests
`advertised`	object	No	Contains settings for the advertised API address and port. See advertised options
`cleanup_timeout`	string	No	Sets the timeout for cleanup operations
`keep_alive`	string	No	Defines the keep-alive timeout for connections
`pid_file`	string	No	Specifies the path to the file where the API's PID will be written
`uid`	integer	No	User id value to set on start
`gid`	integer	No	Group id value to set on start
`tls`	object	No	Contains settings for TLS encryption. See TLS options
`scheme`	array of strings	No	Enabled listeners
`userlist`	object	No	Contains settings for userlist. See userlist options
`transaction`	object	No	Contains settings for transactions. See transaction options
`resources`	object	No	Contains settings for resources. See resources options
`user`	array of objects	No	List of users. See user options

dataplaneapi.advertised Configuration Options

Option	Type	Required	Description
`api_address`	string	No	The advertised API address
`api_port`	integer	No	The advertised API port

dataplaneapi.tls Configuration Options

Option	Type	Required	Description
`tls_host`	string	No	The host address for TLS connections
`tls_port`	integer	No	The port number for TLS connections
`tls_certificate`	string	No	Path to the TLS certificate file
`tls_key`	string	No	Path to the TLS certificate key file
`tls_ca`	string	No	Path to the TLS CA certificate file
`tls_listen_limit`	integer	No	The maximum number of TLS connections
`tls_keep_alive`	string	No	The keep-alive timeout for TLS connections
`tls_read_timeout`	string	No	The read timeout for TLS connections
`tls_write_timeout`	string	No	The write timeout for TLS connections

dataplaneapi.userlist Configuration Options

Option	Type	Required	Description
`userlist`	string	No	Userlist in HAProxy configuration to use for API Basic Authentication
`userlist_file`	string	No	Path to the dataplaneapi userlist file

dataplaneapi.transaction Configuration Options

Option	Type	Required	Description
`transaction_dir`	string	No	Path to the transaction directory
`backups_number`	integer	No	Number of backup configuration files to keep
`backups_dir`	string	No	Path to directory in which to place backup files
`max_open_transactions`	integer	No	Limit for active transaction in pending state

dataplaneapi.resources Configuration Options

Option	Type	Required	Description
`maps_dir`	string	No	Path to directory of map files managed by dataplane
`ssl_certs_dir`	string	No	Path to SSL certificates directory
`general_storage_dir`	string	No	Path to general storage directory
`dataplane_storage_dir`	string	No	Path to dataplane internal storage directory
`update_map_files`	boolean	No	Flag used for syncing map files with runtime maps values
`update_map_files_period`	integer	No	Elapsed time in seconds between two maps syncing operations
`spoe_dir`	string	No	Path to SPOE directory
`spoe_transaction_dir`	string	No	Path to the SPOE transaction directory

dataplaneapi.user Configuration Options

Option	Type	Required	Description
`name`	string	Yes	User name
`password`	string	Yes	Password
`insecure`	boolean	No	Insecure password

haproxy Configuration Options

Option	Type	Required	Description
`config_file`	string	No	Path to the HAProxy configuration file
`haproxy_bin`	string	No	Path to the HAProxy binary file
`master_runtime`	string	No	Path to the master Runtime API socket
`fid`	string	No	Path to file that will dataplaneapi use to write its id
`master_worker_mode`	boolean	No	Flag to enable helpers when running HAProxy in master worker mode
`reload`	object	No	Contains settings for reloading HAProxy. See reload options
`delayed_start_max`	string	No	Maximum duration to wait for the haproxy runtime socket to be ready
`delayed_start_tick`	string	No	Duration between checks for the haproxy runtime socket to be ready

haproxy.reload Configuration Options

Option	Type	Required	Description
`reload_delay`	integer	No	Minimum delay between two reloads (in s)
`reload_cmd`	string	No	Reload command
`restart_cmd`	string	No	Restart command
`status_cmd`	string	No	Status command
`service_name`	string	No	Name of the HAProxy service
`reload_retention`	integer	No	Reload retention in days
`reload_strategy`	string	No	Either systemd, s6 or custom
`validate_cmd`	string	No	Executes a custom command to perform the HAProxy configuration check

log_targets Configuration Options

This section contains settings related to log targets.

log_targets: (array of objects, optional) - List of log targets.

The log_targets option allows you to define multiple destinations for log messages. Each element in the log_targets array is an object that defines a specific log target. Each log target object can have the following properties:

Option	Type	Required	Description
`log_to`	string	Yes	Type of log target: 'file', 'syslog', or 'stdout'
`log_format`	string	No	Log format for this target: 'text', 'json', or 'apache_common'. Default is 'text'
`log_level`	string	No	Log level: 'trace', 'debug', 'info', 'warning', 'error', or 'critical'. Default is 'info'
`log_file`	string	No	If target is 'file', specifies the path to the log file
`acl_format`	string	No	Apache Common Log Format to format the access log entries, default:"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\" %{us}T"
`syslog_address`	string	No	If target is 'syslog', specifies the syslog server address
`syslog_protocol`	string	No	If target is 'syslog', specifies the syslog protocol (e.g., 'udp', 'tcp')
`syslog_tag`	string	No	If target is 'syslog', specifies the syslog tag
`syslog_facility`	string	No	If target is 'syslog', define the Syslog facility number, allowed values: 'kern', 'user', 'mail', 'daemon', 'auth', 'syslog', 'lpr', 'news', 'uucp', 'cron', 'authpriv', 'ftp', 'local0', 'local1', 'local2', 'local3', 'local4', 'local5', 'local6', 'local7'
`syslog_level`	string	No	If target is 'syslog', define the required syslog messages level, allowed values: 'debug', 'info', 'notice', 'warning', 'error', 'critical', 'alert', 'emergency'
`log_types`	array of strings	No	Define which log types to log to this target, allowed values: 'app', 'access'

Example of log_targets:

log_targets:
  - log_target: file
    log_file: /var/log/dataplaneapi.log
    log_format: json
    log_level: debug
    log_types:
      - access
      - app
  - log_target: syslog
    syslog_address: 127.0.0.1:514
    syslog_protocol: udp
    syslog_tag: dataplaneapi
    syslog_facility: local0
    log_level: info
    log_types:
      - access
  - log_target: stdout
    log_format: text
    log_level: warning
    log_types:
      - access
      - app

Command-Line Overrides

Many of the configuration options available in the YAML file can be overridden by command-line arguments when starting the Data Plane API. This allows for flexibility in deployment and testing.

CLI Argument Precedence

When a configuration option is set both in the YAML file and via a command-line argument, the command-line argument takes precedence.

Common CLI Flags

-c, --config-file: Overrides the haproxy.config_file option.
-b, --haproxy-bin: Overrides the haproxy.haproxy_bin option.
-m, --master-runtime: Overrides the haproxy.master_runtime option.
-u, --userlist: Overrides the dataplaneapi.userlist.userlist option.
-d, --reload-delay: Overrides the haproxy.reload.reload_delay option.
-r, --reload-cmd: Overrides the haproxy.reload.reload_cmd option.
-s, --restart-cmd: Overrides the haproxy.reload.restart_cmd option.
-t, --transaction-dir: Overrides the dataplaneapi.transaction.transaction_dir option.
-n, --backups-number: Overrides the dataplaneapi.transaction.backups_number option.
-p, --maps-dir: Overrides the dataplaneapi.resources.maps_dir option.
-i, --show-system-info: Overrides the dataplaneapi.show_system_info option.
--disable-inotify: Overrides the dataplaneapi.disable_inotify option.
--pid-file: Overrides the dataplaneapi.pid_file option.
--debug-socket-path: Overrides the dataplaneapi.debug_socket_path option.
--uid: Overrides the dataplaneapi.uid option.
--gid: Overrides the dataplaneapi.gid option.
--userlist-file: Overrides the dataplaneapi.userlist.userlist_file option.
--status-cmd: Overrides the haproxy.reload.status_cmd option.
--service: Overrides the haproxy.reload.service_name option.
--reload-retention: Overrides the haproxy.reload.reload_retention option.
--reload-strategy: Overrides the haproxy.reload.reload_strategy option.
--validate-cmd: Overrides the haproxy.reload.validate_cmd option.
--backups-dir: Overrides the dataplaneapi.transaction.backups_dir option.
--max-open-transactions: Overrides the dataplaneapi.transaction.max_open_transactions option.
--ssl-certs-dir: Overrides the dataplaneapi.resources.ssl_certs_dir option.
--general-storage-dir: Overrides the dataplaneapi.resources.general_storage_dir option.
--dataplane-storage-dir: Overrides the dataplaneapi.resources.dataplane_storage_dir option.
--update-map-files: Overrides the dataplaneapi.resources.update_map_files option.
--update-map-files-period: Overrides the dataplaneapi.resources.update_map_files_period option.
--spoe-dir: Overrides the dataplaneapi.resources.spoe_dir option.
--spoe-transaction-dir: Overrides the dataplaneapi.resources.spoe_transaction_dir option.
--api-address: Overrides the dataplaneapi.advertised.api_address option.
--api-port: Overrides the dataplaneapi.advertised.api_port option.
--syslog-address: Overrides the log.syslog.syslog_address option.
--syslog-protocol: Overrides the log.syslog.syslog_protocol option.
--syslog-tag: Overrides the log.syslog.syslog_tag option.
--syslog-level: Overrides the log.syslog.syslog_level option.
--syslog-facility: Overrides the log.syslog.syslog_facility option.
--log-to: Overrides the log.log_to option.
--log-file: Overrides the log.log_file option.
--log-level: Overrides the log.log_level option.
--log-format: Overrides the log.log_format option.
--apache-common-log-format: Overrides the log.apache_common_log_format option.
--master-worker-mode: Overrides the haproxy.master_worker_mode option.
--delayed-start-max: Overrides the haproxy.delayed_start_max option.
--delayed-start-tick: Overrides the haproxy.delayed_start_tick option.
--fid: Overrides the haproxy.fid option.

Example Configuration

config_version: 2
name: haproxy-dataplaneapi
dataplaneapi:
  host: 0.0.0.0
  port: 5555
  scheme:
  - http
  users:
    name: admin
    passowrd: adminpwd
    insecure: true
  transaction:
    transaction_dir: /etc/haproxy/transactions
    backups_number: 10
    backups_dir: /etc/haproxy/backups
    max_open_transactions: 10
  resources:
    maps_dir: /etc/haproxy/maps
    ssl_certs_dir: /etc/haproxy/ssl
    general_storage_dir: /etc/haproxy/general
    spoe_dir: /etc/haproxy/spoe
    dataplane_storage_dir: /etc/haproxy/dataplane
haproxy:
  config_file: /etc/haproxy/haproxy.cfg
  haproxy_bin: /usr/sbin/haproxy
  master_worker_mode: true
  master_runtime: /var/run/haproxy/master.sock
  reload:
    reload_delay: 5
    service_name: haproxy
    reload_strategy: systemd
log_targets:
- log_to: file
  log_file: /var/log/haproxy-dataplaneapi.log
  log_level: info
  log_types:
  - access
  - app