Reference

Configuration file reference

On this page

At startup, HAProxy Data Plane API reads its YAML configuration file to determine how to run. This file allows you to set various directives that control the behavior of the API and its interaction with HAProxy. It’s structured into several sections, each corresponding to a different aspect of HAProxy Data Plane API’s functionality.

Edit the configuration file Jump to heading

To edit the API’s configuration file:

  • For Data Plane API 2.8 and beyond, edit the file /etc/haproxy/dataplaneapi.yml.
  • For Data Plane API 2.7 and earlier, edit the file /etc/haproxy/dataplaneapi.hcl.
  • For Data Plane API version 2.8 and beyond, edit the configuration file /etc/hapee-extras/dataplaneapi.yml.
  • For Data Plane API version 2.7 and earlier, edit the configuration file /etc/hapee-extras/dataplaneapi.hcl.
  • From the Tools tab, use the File Manager to edit the file /app/management/var/lib/dataplaneapi/dataplaneapi.yaml.
  • After making changes, save the file. Then restart the dataplaneapi service on the Services tab.
  • To make your changes persistent after a reboot, click the Setup tab. Then click Save under Configuration.

Example configuration file Jump to heading

Here’s an example configuration file.

yaml
config_version: 2
name: famous_condor # string
dataplaneapi:
  scheme: # []string
  - http
  cleanup_timeout: "10s" # time.Duration
  graceful_timeout: "15s" # time.Duration
  max_header_size: "1MiB" # flagext.ByteSize
  max_body_size: "1GiB" # flagext.ByteSize
  socket_path: "/var/run/data-plane.sock" # flags.Filename
  debug_socket_path: "/var/run/dataplane-debug.sock" #string
  host: "localhost" # string
  port: 80 # int
  listen_limit: 1024 # int
  keep_alive: "3m" # time.Duration
  read_timeout: "30s" # time.Duration
  write_timeout: "60s" # time.Duration
  show_system_info: false # bool
  disable_inotify: false # bool
  pid_file: /tmp/dataplane.pid # string
  uid: 1000 # int
  gid: 1000 # int
  tls:
    tls_host: null # string
    tls_port: 6443 # int
    tls_certificate: /etc/haproxy/ssl/certs/server-cert.pem # flags.Filename
    tls_key: /etc/haproxy/ssl/certs/server-key.pem # flags.Filename
    tls_ca: null # flags.Filename
    tls_listen_limit: 10 # int
    tls_keep_alive: 1m # time.Duration
    tls_read_timeout: 10s # time.Duration
    tls_write_timeout: 10s # time.Duration
  user:
    - name: admin # string
      insecure: true # bool
      password: adminpwd # string
  userlist:
    userlist: "dataplaneapi" # string
    userlist_file: /etc/haproxy/haproxy.cfg # string
  transaction:
    transaction_dir: /tmp/haproxy # string
    backups_number: 0 # int
    backups_dir: /tmp/backups # string
    max_open_transactions: 20 # int64
  resources:
    maps_dir: "/etc/haproxy/maps" # string
    ssl_certs_dir: "/etc/haproxy/ssl" # string
    update_map_files: false # bool
    update_map_files_period: 10 # int64
    spoe_dir: "/etc/haproxy/spoe" # string
    spoe_transaction_dir: /tmp/spoe-haproxy # string
    dataplane_storage_dir: "/etc/haproxy/general" # string
  advertised:
    api_address: 10.2.3.4 # string
    api_port: 80 # int64
haproxy:
  config_file: "/etc/haproxy/haproxy.cfg" # string
  haproxy_bin: "haproxy" # string
  master_runtime: null # string
  fid: null # string
  master_worker_mode: false # bool
  delayed_start_max: 30s # time.Duration
  delayed_start_tick: 500ms # time.Duration
  preferred_time_suffix: nearest # enum [nearest, none, ms, s, m, h, d]
  reload:
    reload_delay: 5 # int
    reload_cmd: "systemctl reload haproxy"
    restart_cmd: "systemctl restart haproxy"
    status_cmd: "systemctl status haproxy"
    service_name: "haproxy.service"
    reload_retention: 1 # int
    reload_strategy: custom
    validate_cmd: null # string
    validate_files_before:
    - "/etc/haproxy/global.def"
    validate_files_after: [] # []string
log_targets:
- log_to: stdout
  log_level: debug
  log_format: json
  log_types:
  - access
  - app
- log_to: file
  log_file: /var/log/dataplanepi.log
  log_level: info
  log_format: text
  log_types:
  - app
- log_to: syslog
  log_level: info
  syslog_address: 127.0.0.1
  syslog_protocol: tcp
  syslog_tag: dataplaneapi
  syslog_level: debug
  syslog_facility: local0
  log_types:
  - access
yaml
config_version: 2
name: famous_condor # string
dataplaneapi:
  scheme: # []string
  - http
  cleanup_timeout: "10s" # time.Duration
  graceful_timeout: "15s" # time.Duration
  max_header_size: "1MiB" # flagext.ByteSize
  max_body_size: "1GiB" # flagext.ByteSize
  socket_path: "/var/run/data-plane.sock" # flags.Filename
  debug_socket_path: "/var/run/dataplane-debug.sock" #string
  host: "localhost" # string
  port: 80 # int
  listen_limit: 1024 # int
  keep_alive: "3m" # time.Duration
  read_timeout: "30s" # time.Duration
  write_timeout: "60s" # time.Duration
  show_system_info: false # bool
  disable_inotify: false # bool
  pid_file: /tmp/dataplane.pid # string
  uid: 1000 # int
  gid: 1000 # int
  tls:
    tls_host: null # string
    tls_port: 6443 # int
    tls_certificate: /etc/haproxy/ssl/certs/server-cert.pem # flags.Filename
    tls_key: /etc/haproxy/ssl/certs/server-key.pem # flags.Filename
    tls_ca: null # flags.Filename
    tls_listen_limit: 10 # int
    tls_keep_alive: 1m # time.Duration
    tls_read_timeout: 10s # time.Duration
    tls_write_timeout: 10s # time.Duration
  user:
    - name: admin # string
      insecure: true # bool
      password: adminpwd # string
  userlist:
    userlist: "dataplaneapi" # string
    userlist_file: /etc/haproxy/haproxy.cfg # string
  transaction:
    transaction_dir: /tmp/haproxy # string
    backups_number: 0 # int
    backups_dir: /tmp/backups # string
    max_open_transactions: 20 # int64
  resources:
    maps_dir: "/etc/haproxy/maps" # string
    ssl_certs_dir: "/etc/haproxy/ssl" # string
    update_map_files: false # bool
    update_map_files_period: 10 # int64
    spoe_dir: "/etc/haproxy/spoe" # string
    spoe_transaction_dir: /tmp/spoe-haproxy # string
    dataplane_storage_dir: "/etc/haproxy/general" # string
  advertised:
    api_address: 10.2.3.4 # string
    api_port: 80 # int64
haproxy:
  config_file: "/etc/haproxy/haproxy.cfg" # string
  haproxy_bin: "haproxy" # string
  master_runtime: null # string
  fid: null # string
  master_worker_mode: false # bool
  delayed_start_max: 30s # time.Duration
  delayed_start_tick: 500ms # time.Duration
  preferred_time_suffix: nearest # enum [nearest, none, ms, s, m, h, d]
  reload:
    reload_delay: 5 # int
    reload_cmd: "systemctl reload haproxy"
    restart_cmd: "systemctl restart haproxy"
    status_cmd: "systemctl status haproxy"
    service_name: "haproxy.service"
    reload_retention: 1 # int
    reload_strategy: custom
    validate_cmd: null # string
    validate_files_before:
    - "/etc/haproxy/global.def"
    validate_files_after: [] # []string
log_targets:
- log_to: stdout
  log_level: debug
  log_format: json
  log_types:
  - access
  - app
- log_to: file
  log_file: /var/log/dataplanepi.log
  log_level: info
  log_format: text
  log_types:
  - app
- log_to: syslog
  log_level: info
  syslog_address: 127.0.0.1
  syslog_protocol: tcp
  syslog_tag: dataplaneapi
  syslog_level: debug
  syslog_facility: local0
  log_types:
  - access
yaml
config_version: 2
name: lb01
dataplaneapi:
  scheme: [https]
  host: 127.0.0.1
  port: 5555
  socket_path: /var/run/hapee-extras/dataplaneapi.sock
  debug_socket_path: /var/run/hapee-extras/dataplaneapi-debug.sock
  listen_limit: 1024
  cleanup_timeout: 10s
  graceful_timeout: 15s
  keep_alive: 3m
  read_timeout: 30s
  write_timeout: 60s
  max_header_size: 1MiB
  max_body_size: 1GiB
  show_system_info: false
  disable_inotify: false
  pam: false
  pid_file: /run/hapee-extras-dataplaneapi.pid
  uid: 0
  gid: 0
  tls:
    tls_host: 192.0.2.10
    tls_port: 6443
    tls_certificate: /etc/hapee-extras/ssl/dataplaneapi.crt
    tls_key: /etc/hapee-extras/ssl/dataplaneapi.key
    tls_listen_limit: 1024
    tls_keep_alive: 3m
    tls_read_timeout: 30s
    tls_write_timeout: 60s
  user:
    - name: admin
      insecure: true
      password: change-this-example-password
  transaction:
    transaction_dir: /var/run/hapee-extras/dataplaneapi
    backups_number: 10
    backups_dir: /etc/hapee-3.4/backups
    max_open_transactions: 20
    disable_persistent_transactions: false
  resources:
    maps_dir: /etc/hapee-3.4/maps
    ssl_certs_dir: /etc/hapee-3.4/ssl
    ssl_certs_aloha: false
    general_storage_dir: /etc/hapee-3.4/general
    dataplane_storage_dir: /etc/hapee-3.4/dataplane
    waf_dir: /etc/hapee-3.4
    update_map_files: false
    update_map_files_period: 10
    spoe_dir: /etc/hapee-3.4/spoe
    spoe_transaction_dir: /var/run/hapee-extras/dataplaneapi/spoe
  advertised:
    api_address: lb01.example.com
    api_port: 6443
haproxy:
  config_file: /etc/hapee-3.4/hapee-lb.cfg
  haproxy_bin: /opt/hapee-3.4/sbin/hapee-lb
  master_runtime: /run/hapee-lb-master.sock
  fid: /etc/hapee-3.4/dataplane/node-id
  master_worker_mode: false
  delayed_start_max: 30s
  delayed_start_tick: 500ms
  reload:
    reload_strategy: custom
    service_name: hapee-3.4-lb
    reload_cmd: /usr/bin/systemctl reload hapee-3.4-lb
    restart_cmd: /usr/bin/systemctl restart hapee-3.4-lb
    start_cmd: /usr/bin/systemctl start hapee-3.4-lb
    stop_cmd: /usr/bin/systemctl stop hapee-3.4-lb
    status_cmd: /usr/bin/systemctl --quiet is-active hapee-3.4-lb
    reload_delay: 5
    reload_retention: 1
    validate_cmd: "" # Use the built-in HAProxy binary validator.
    validate_files_before:
      - /etc/hapee-3.4/global.cfg
    validate_files_after:
      - /etc/hapee-3.4/backends.cfg
keepalived:
  config_file: /etc/hapee-extras/hapee-vrrp.cfg
  start_cmd: /usr/bin/systemctl start hapee-extras-vrrp
  reload_cmd: /usr/bin/systemctl reload hapee-extras-vrrp
  restart_cmd: /usr/bin/systemctl restart hapee-extras-vrrp
  stop_cmd: /usr/bin/systemctl stop hapee-extras-vrrp
  status_cmd: /usr/bin/systemctl --quiet is-active hapee-extras-vrrp
  getpid_cmd: /usr/bin/pgrep hapee-vrrp
  signal_cmd: /bin/kill
  read_dump_cmd: /bin/cat
  validate_cmd: /bin/sh -c '/opt/hapee-extras/sbin/hapee-vrrp --config-test -f "$KEEPALIVED_TRANSACTION_FILE"'
  reload_delay: 5
  transaction_dir: /etc/hapee-extras/keepalived/transactions
  backups_dir: /etc/hapee-extras/keepalived/backups
  backups_number: 10
gslb:
  config_file: /etc/hapee-extras/hapee-gslb.conf
  transaction_dir: /etc/hapee-extras/gslb/transactions
  reload_cmd: /usr/bin/systemctl reload hapee-extras-gslb
  restart_cmd: /usr/bin/systemctl restart hapee-extras-gslb
  start_cmd: /usr/bin/systemctl start hapee-extras-gslb
  stop_cmd: /usr/bin/systemctl stop hapee-extras-gslb
  validate_bin: /opt/hapee-extras/sbin/hapee-gslb
  backups_dir: /etc/hapee-extras/gslb/backups
  backups_number: 10
  disable_save_verification: false
log_targets:
  - log_to: stdout
    log_level: info
    log_format: text
    log_types: [app]
  - log_to: file
    log_file: /var/log/hapee-dataplaneapi.log
    log_level: info
    log_format: json
    acl_format: '%h %l %u %t "%m %U%q %H" %>s %b "%{Referer}i" "%{User-agent}i"'
    log_types: [app, access]
  - log_to: syslog
    log_level: info
    log_format: text
    syslog_address: 127.0.0.1:514
    syslog_protocol: tcp
    syslog_tag: hapee-dataplaneapi
    syslog_level: info
    syslog_facility: local0
    log_types: [app, access]
yaml
config_version: 2
name: lb01
dataplaneapi:
  scheme: [https]
  host: 127.0.0.1
  port: 5555
  socket_path: /var/run/hapee-extras/dataplaneapi.sock
  debug_socket_path: /var/run/hapee-extras/dataplaneapi-debug.sock
  listen_limit: 1024
  cleanup_timeout: 10s
  graceful_timeout: 15s
  keep_alive: 3m
  read_timeout: 30s
  write_timeout: 60s
  max_header_size: 1MiB
  max_body_size: 1GiB
  show_system_info: false
  disable_inotify: false
  pam: false
  pid_file: /run/hapee-extras-dataplaneapi.pid
  uid: 0
  gid: 0
  tls:
    tls_host: 192.0.2.10
    tls_port: 6443
    tls_certificate: /etc/hapee-extras/ssl/dataplaneapi.crt
    tls_key: /etc/hapee-extras/ssl/dataplaneapi.key
    tls_listen_limit: 1024
    tls_keep_alive: 3m
    tls_read_timeout: 30s
    tls_write_timeout: 60s
  user:
    - name: admin
      insecure: true
      password: change-this-example-password
  transaction:
    transaction_dir: /var/run/hapee-extras/dataplaneapi
    backups_number: 10
    backups_dir: /etc/hapee-3.4/backups
    max_open_transactions: 20
    disable_persistent_transactions: false
  resources:
    maps_dir: /etc/hapee-3.4/maps
    ssl_certs_dir: /etc/hapee-3.4/ssl
    ssl_certs_aloha: false
    general_storage_dir: /etc/hapee-3.4/general
    dataplane_storage_dir: /etc/hapee-3.4/dataplane
    waf_dir: /etc/hapee-3.4
    update_map_files: false
    update_map_files_period: 10
    spoe_dir: /etc/hapee-3.4/spoe
    spoe_transaction_dir: /var/run/hapee-extras/dataplaneapi/spoe
  advertised:
    api_address: lb01.example.com
    api_port: 6443
haproxy:
  config_file: /etc/hapee-3.4/hapee-lb.cfg
  haproxy_bin: /opt/hapee-3.4/sbin/hapee-lb
  master_runtime: /run/hapee-lb-master.sock
  fid: /etc/hapee-3.4/dataplane/node-id
  master_worker_mode: false
  delayed_start_max: 30s
  delayed_start_tick: 500ms
  reload:
    reload_strategy: custom
    service_name: hapee-3.4-lb
    reload_cmd: /usr/bin/systemctl reload hapee-3.4-lb
    restart_cmd: /usr/bin/systemctl restart hapee-3.4-lb
    start_cmd: /usr/bin/systemctl start hapee-3.4-lb
    stop_cmd: /usr/bin/systemctl stop hapee-3.4-lb
    status_cmd: /usr/bin/systemctl --quiet is-active hapee-3.4-lb
    reload_delay: 5
    reload_retention: 1
    validate_cmd: "" # Use the built-in HAProxy binary validator.
    validate_files_before:
      - /etc/hapee-3.4/global.cfg
    validate_files_after:
      - /etc/hapee-3.4/backends.cfg
keepalived:
  config_file: /etc/hapee-extras/hapee-vrrp.cfg
  start_cmd: /usr/bin/systemctl start hapee-extras-vrrp
  reload_cmd: /usr/bin/systemctl reload hapee-extras-vrrp
  restart_cmd: /usr/bin/systemctl restart hapee-extras-vrrp
  stop_cmd: /usr/bin/systemctl stop hapee-extras-vrrp
  status_cmd: /usr/bin/systemctl --quiet is-active hapee-extras-vrrp
  getpid_cmd: /usr/bin/pgrep hapee-vrrp
  signal_cmd: /bin/kill
  read_dump_cmd: /bin/cat
  validate_cmd: /bin/sh -c '/opt/hapee-extras/sbin/hapee-vrrp --config-test -f "$KEEPALIVED_TRANSACTION_FILE"'
  reload_delay: 5
  transaction_dir: /etc/hapee-extras/keepalived/transactions
  backups_dir: /etc/hapee-extras/keepalived/backups
  backups_number: 10
gslb:
  config_file: /etc/hapee-extras/hapee-gslb.conf
  transaction_dir: /etc/hapee-extras/gslb/transactions
  reload_cmd: /usr/bin/systemctl reload hapee-extras-gslb
  restart_cmd: /usr/bin/systemctl restart hapee-extras-gslb
  start_cmd: /usr/bin/systemctl start hapee-extras-gslb
  stop_cmd: /usr/bin/systemctl stop hapee-extras-gslb
  validate_bin: /opt/hapee-extras/sbin/hapee-gslb
  backups_dir: /etc/hapee-extras/gslb/backups
  backups_number: 10
  disable_save_verification: false
log_targets:
  - log_to: stdout
    log_level: info
    log_format: text
    log_types: [app]
  - log_to: file
    log_file: /var/log/hapee-dataplaneapi.log
    log_level: info
    log_format: json
    acl_format: '%h %l %u %t "%m %U%q %H" %>s %b "%{Referer}i" "%{User-agent}i"'
    log_types: [app, access]
  - log_to: syslog
    log_level: info
    log_format: text
    syslog_address: 127.0.0.1:514
    syslog_protocol: tcp
    syslog_tag: hapee-dataplaneapi
    syslog_level: info
    syslog_facility: local0
    log_types: [app, access]
yaml
config_version: 2
name: ALOHA1
dataplaneapi:
  host: 0.0.0.0
  port: 5555
  advertised:
    api_address: ""
    api_port: 0
  tls:
    tls_host: 0.0.0.0
    tls_port: 6443
    tls_certificate: /etc/ssl/frontends/default/crt.pem
    tls_key: /etc/ssl/frontends/default/key.pem
  scheme:
  - http
  userlist:
    userlist: controller
    userlist_file: ""
  transaction:
    transaction_dir: /app/management/var/state/dataplaneapi
    backups_number: 10
    backups_dir: /app/management/var/backups/dataplaneapi
  resources:
    maps_dir: /app/management/var/lib/dataplaneapi/maps
    ssl_certs_dir: /app/management/var/lib/dataplaneapi/ssl
    general_storage_dir: /app/management/var/lib/dataplaneapi/general
    dataplane_storage_dir: /app/management/var/lib/dataplaneapi/storage
    waf_dir: /app/management/var/lib/dataplaneapi/waf
    spoe_dir: /app/management/var/lib/dataplaneapi/spoe
    spoe_transaction_dir: /app/management/var/state/dataplaneapi/spoe
haproxy:
  reload:
    reload_delay: 5
    reload_strategy: custom
log_targets:
- log_to: syslog
  log_level: warning
  syslog_address: 127.0.0.11:514
  syslog_protocol: udp4
  syslog_tag: dataplaneapi
  syslog_level: warning
  syslog_facility: local0
  log_types:
  - access
  - app
yaml
config_version: 2
name: ALOHA1
dataplaneapi:
  host: 0.0.0.0
  port: 5555
  advertised:
    api_address: ""
    api_port: 0
  tls:
    tls_host: 0.0.0.0
    tls_port: 6443
    tls_certificate: /etc/ssl/frontends/default/crt.pem
    tls_key: /etc/ssl/frontends/default/key.pem
  scheme:
  - http
  userlist:
    userlist: controller
    userlist_file: ""
  transaction:
    transaction_dir: /app/management/var/state/dataplaneapi
    backups_number: 10
    backups_dir: /app/management/var/backups/dataplaneapi
  resources:
    maps_dir: /app/management/var/lib/dataplaneapi/maps
    ssl_certs_dir: /app/management/var/lib/dataplaneapi/ssl
    general_storage_dir: /app/management/var/lib/dataplaneapi/general
    dataplane_storage_dir: /app/management/var/lib/dataplaneapi/storage
    waf_dir: /app/management/var/lib/dataplaneapi/waf
    spoe_dir: /app/management/var/lib/dataplaneapi/spoe
    spoe_transaction_dir: /app/management/var/state/dataplaneapi/spoe
haproxy:
  reload:
    reload_delay: 5
    reload_strategy: custom
log_targets:
- log_to: syslog
  log_level: warning
  syslog_address: 127.0.0.11:514
  syslog_protocol: udp4
  syslog_tag: dataplaneapi
  syslog_level: warning
  syslog_facility: local0
  log_types:
  - access
  - app

Top-level directives Jump to heading

HAProxy Data Plane API supports the following top-level configuration file directives.

config_version Jump to heading

The top-level config_version directive sets the file’s configuration version.

  • Parent: none
  • Type: integer
  • Required: false
yaml
config_version: 2
yaml
config_version: 2

name Jump to heading

The top-level name directive assigns a name to this API server. Defaults to the hostname.

  • Parent: none
  • Type: string
  • Required: false
yaml
name: famous_condor
yaml
name: famous_condor

dataplaneapi directives Jump to heading

HAProxy Data Plane API supports the following configuration file directives in its dataplaneapi section.

advertised Jump to heading

The dataplaneapi section’s advertised directive contains settings for the advertised API address and port. See advertised directives.

  • Parent: dataplaneapi
  • Type: object
  • Required: false
yaml
dataplaneapi:
  advertised:
    api_address: 10.2.3.4
    api_port: 80
yaml
dataplaneapi:
  advertised:
    api_address: 10.2.3.4
    api_port: 80

cleanup_timeout Jump to heading

The dataplaneapi section’s cleanup_timeout directive sets the timeout for cleaning up idle connections. Defaults to 10s.

  • Parent: dataplaneapi
  • Type: string
  • Required: false
yaml
dataplaneapi:
  cleanup_timeout: "10s"
yaml
dataplaneapi:
  cleanup_timeout: "10s"

debug_socket_path Jump to heading

The dataplaneapi section’s debug_socket_path directive defines the path for the debugging command socket. See Debugging. Set it to an empty string to disable it.

  • Parent: dataplaneapi
  • Type: string
  • Required: false
yaml
dataplaneapi:
  debug_socket_path: /var/run/dataplane-debug.sock
yaml
dataplaneapi:
  debug_socket_path: /var/run/dataplane-debug.sock

disable_inotify Jump to heading

The dataplaneapi section’s disable_inotify directive disables configuration file filesystem watching.

  • Parent: dataplaneapi
  • Type: boolean
  • Required: false
yaml
dataplaneapi:
  disable_inotify: false
yaml
dataplaneapi:
  disable_inotify: false

gid Jump to heading

The dataplaneapi section’s gid directive sets the process’s group ID value to set on start. When set, the API switching to this group and clears supplementary groups. Set it to 0 to leave it unchanged.

  • Parent: dataplaneapi
  • Type: integer
  • Required: false
yaml
dataplaneapi:
  gid: 1000
yaml
dataplaneapi:
  gid: 1000

graceful_timeout Jump to heading

The dataplaneapi section’s graceful_timeout directive sets the server shutdown grace period. Defaults to 15s.

  • Parent: dataplaneapi
  • Type: string
  • Required: false
yaml
dataplaneapi:
  graceful_timeout: "15s"
yaml
dataplaneapi:
  graceful_timeout: "15s"

host Jump to heading

The dataplaneapi section’s host directive sets the API’s HTTP bind address. Defaults to localhost.

  • Parent: dataplaneapi
  • Type: string
  • Required: false
yaml
dataplaneapi:
  host: "localhost"
yaml
dataplaneapi:
  host: "localhost"

keep_alive Jump to heading

The dataplaneapi section’s keep_alive directive sets the TCP keep-alive timeout on accepted connections. It prunes dead TCP connections, for example when the client closes their laptop mid-download. Defaults to 3m.

  • Parent: dataplaneapi
  • Type: string
  • Required: false
yaml
dataplaneapi:
  keep_alive: 3m
yaml
dataplaneapi:
  keep_alive: 3m

listen_limit Jump to heading

The dataplaneapi section’s listen_limit directive sets the maximum number of simultaneous HTTP connections the API can handle. Set it to 0 for unlimited.

  • Parent: dataplaneapi
  • Type: integer
  • Required: false
yaml
dataplaneapi:
  listen_limit: 1024
yaml
dataplaneapi:
  listen_limit: 1024

max_body_size Jump to heading

This section applies to:

  • HAProxy Data Plane API 3.4 and newer

The dataplaneapi section’s max_body_size directive controls the maximum number of bytes the server will read from a request body before aborting the request. Set it to 0 for unlimited. Defaults to 1GiB.

  • Parent: dataplaneapi
  • Type: string
  • Required: false
yaml
dataplaneapi:
  max_body_size: "1MiB"
yaml
dataplaneapi:
  max_body_size: "1MiB"

max_header_size Jump to heading

The dataplaneapi section’s max_header_size directive defines the maximum HTTP request header size for API requests. Defaults to 1MiB.

  • Parent: dataplaneapi
  • Type: string
  • Required: false
yaml
dataplaneapi:
  max_header_size: "1MiB"
yaml
dataplaneapi:
  max_header_size: "1MiB"

pam Jump to heading

Enterprise feature

This is an enterprise feature.

The dataplaneapi section’s pam directive enables using PAM instead of Basic Authentication.

  • Parent: dataplaneapi
  • Type: boolean
  • Required: false
yaml
dataplaneapi:
  pam: true
yaml
dataplaneapi:
  pam: true

pid_file Jump to heading

The dataplaneapi section’s pid_file directive specifies the path to the file where the API’s PID will be written.

  • Parent: dataplaneapi
  • Type: string
  • Required: false
yaml
dataplaneapi:
  pid_file: /tmp/dataplane.pid
yaml
dataplaneapi:
  pid_file: /tmp/dataplane.pid

port Jump to heading

The dataplaneapi section’s port directive defines the TCP port number for the API. Set it to 0 to select an available port.

  • Parent: dataplaneapi
  • Type: integer
  • Required: false
yaml
dataplaneapi:
  port: 80
yaml
dataplaneapi:
  port: 80

read_timeout Jump to heading

The dataplaneapi section’s read_timeout directive specifies the HTTP request read timeout for API requests. Defaults to 30s.

  • Parent: dataplaneapi
  • Type: string
  • Required: false
yaml
dataplaneapi:
  read_timeout: "30s"
yaml
dataplaneapi:
  read_timeout: "30s"

resources Jump to heading

The dataplaneapi section’s resources directive contains settings for resources such as map files, certificates, and WAF files. See resources directives.

  • Parent: dataplaneapi
  • Type: object
  • Required: false
yaml
dataplaneapi:
  resources:
    maps_dir: /etc/haproxy/maps
    ssl_certs_dir: /etc/haproxy/ssl
    update_map_files: false
    update_map_files_period: 10
    spoe_dir: /etc/haproxy/spoe
    spoe_transaction_dir: /tmp/spoe-haproxy
    dataplane_storage_dir: /etc/haproxy/general
yaml
dataplaneapi:
  resources:
    maps_dir: /etc/haproxy/maps
    ssl_certs_dir: /etc/haproxy/ssl
    update_map_files: false
    update_map_files_period: 10
    spoe_dir: /etc/haproxy/spoe
    spoe_transaction_dir: /tmp/spoe-haproxy
    dataplane_storage_dir: /etc/haproxy/general

scheme Jump to heading

The dataplaneapi section’s scheme directive sets a list of schemes to enable. It supports http, https, and unix.

  • Parent: dataplaneapi
  • Type: array of strings
  • Required: false
yaml
dataplaneapi:
  scheme:
    - http
yaml
dataplaneapi:
  scheme:
    - http

show_system_info Jump to heading

The dataplaneapi section’s show_system_info directive enables or disables the display of system information on the info endpoint.

  • Parent: dataplaneapi
  • Type: boolean
  • Required: false
yaml
dataplaneapi:
  show_system_info: false
yaml
dataplaneapi:
  show_system_info: false

socket_path Jump to heading

The dataplaneapi section’s socket_path directive specifies the path to the API’s Unix socket. Defaults to /var/run/data-plane.sock.

  • Parent: dataplaneapi
  • Type: string
  • Required: false
yaml
dataplaneapi:
  socket_path: /var/run/data-plane.sock
yaml
dataplaneapi:
  socket_path: /var/run/data-plane.sock

tls Jump to heading

The dataplaneapi section’s tls directive contains settings for TLS encryption. See tls directives.

  • Parent: dataplaneapi
  • Type: object
  • Required: false
yaml
dataplaneapi:
  tls:
    tls_host: 0.0.0.0
    tls_port: 6443
    tls_certificate: /etc/haproxy/ssl/certs/server-cert.pem
    tls_key: /etc/haproxy/ssl/certs/server-key.pem
yaml
dataplaneapi:
  tls:
    tls_host: 0.0.0.0
    tls_port: 6443
    tls_certificate: /etc/haproxy/ssl/certs/server-cert.pem
    tls_key: /etc/haproxy/ssl/certs/server-key.pem

transaction Jump to heading

The dataplaneapi section’s transaction directive contains settings for transactions. See transaction directives.

  • Parent: dataplaneapi
  • Type: object
  • Required: false
yaml
dataplaneapi:
  transaction:
    transaction_dir: /tmp/haproxy
    backups_number: 3
    backups_dir: /tmp/backups
    max_open_transactions: 20
yaml
dataplaneapi:
  transaction:
    transaction_dir: /tmp/haproxy
    backups_number: 3
    backups_dir: /tmp/backups
    max_open_transactions: 20

uid Jump to heading

The dataplaneapi section’s uid directive sets the process’s user ID value to set on start. Set it to 0 to leave it unchanged.

  • Parent: dataplaneapi
  • Type: integer
  • Required: false
yaml
dataplaneapi:
  uid: 1000
yaml
dataplaneapi:
  uid: 1000

user Jump to heading

The dataplaneapi section’s user directive list of users for API Basic Authentication. This is an alternative to setting userlist. See user directives.

  • Parent: dataplaneapi
  • Type: array of objects
  • Required: false
yaml
dataplaneapi:
  user:
    - name: admin
      insecure: true
      password: adminpwd
yaml
dataplaneapi:
  user:
    - name: admin
      insecure: true
      password: adminpwd

userlist Jump to heading

The dataplaneapi section’s userlist directive contains settings for Basic Authentication via a userlist. See userlist directives.

  • Parent: dataplaneapi
  • Type: object
  • Required: false
yaml
dataplaneapi:
  userlist:
    userlist: dataplaneapi
    userlist_file: /etc/haproxy/haproxy.cfg
yaml
dataplaneapi:
  userlist:
    userlist: dataplaneapi
    userlist_file: /etc/haproxy/haproxy.cfg

write_timeout Jump to heading

The dataplaneapi section’s write_timeout directive specifies the HTTP response write timeout for API requests. Defaults to 30s.

  • Parent: dataplaneapi
  • Type: string
  • Required: false
yaml
dataplaneapi:
  write_timeout: "60s"
yaml
dataplaneapi:
  write_timeout: "60s"

dataplaneapi.advertised directives Jump to heading

HAProxy Data Plane API supports the following configuration file directives in its dataplaneapi.advertised section.

api_address Jump to heading

The advertised section’s api_address directive sets the address to advertise to HAProxy Fusion. It isn’t a bind address.

  • Parent: dataplaneapi.advertised
  • Type: string
  • Required: false
yaml
dataplaneapi:
  advertised:
    api_address: 10.2.3.4
yaml
dataplaneapi:
  advertised:
    api_address: 10.2.3.4

api_port Jump to heading

The advertised section’s api_port directive sets the port to advertise to HAProxy Fusion.

  • Parent: dataplaneapi.advertised
  • Type: integer
  • Required: false
yaml
dataplaneapi:
  advertised:
    api_port: 80
yaml
dataplaneapi:
  advertised:
    api_port: 80

dataplaneapi.resources directives Jump to heading

HAProxy Data Plane API supports the following configuration file directives in its dataplaneapi.resources section.

dataplane_storage_dir Jump to heading

The resources section’s dataplane_storage_dir directive sets the path to the internal cluster/discovery storage directory. Defaults to /etc/haproxy/dataplane.

  • Parent: dataplaneapi.resources
  • Type: string
  • Required: false
yaml
dataplaneapi:
  resources:
    dataplane_storage_dir: /etc/haproxy/dataplane
yaml
dataplaneapi:
  resources:
    dataplane_storage_dir: /etc/haproxy/dataplane

general_storage_dir Jump to heading

The resources section’s general_storage_dir directive sets the path to the general-purpose files storage directory.

  • Parent: dataplaneapi.resources
  • Type: string
  • Required: false
yaml
dataplaneapi:
  resources:
    general_storage_dir: /etc/haproxy/general
yaml
dataplaneapi:
  resources:
    general_storage_dir: /etc/haproxy/general

maps_dir Jump to heading

The resources section’s maps_dir directive sets the path to the directory of map files managed by the API.

  • Parent: dataplaneapi.resources
  • Type: string
  • Required: false
yaml
dataplaneapi:
  resources:
    maps_dir: /etc/haproxy/maps
yaml
dataplaneapi:
  resources:
    maps_dir: /etc/haproxy/maps

spoe_dir Jump to heading

The resources section’s spoe_dir directive sets the path to the directory containing Stream Processing Offload Engine (SPOE) configuration files.

  • Parent: dataplaneapi.resources
  • Type: string
  • Required: false
yaml
dataplaneapi:
  resources:
    spoe_dir: /etc/haproxy/spoe
yaml
dataplaneapi:
  resources:
    spoe_dir: /etc/haproxy/spoe

spoe_transaction_dir Jump to heading

The resources section’s spoe_transaction_dir directive sets the path to the directory containing Stream Processing Offload Engine (SPOE) transaction files.

  • Parent: dataplaneapi.resources
  • Type: string
  • Required: false
yaml
dataplaneapi:
  resources:
    spoe_transaction_dir: /tmp/spoe-haproxy
yaml
dataplaneapi:
  resources:
    spoe_transaction_dir: /tmp/spoe-haproxy

ssl_certs_aloha Jump to heading

Enterprise feature

This is an enterprise feature.

The resources section’s ssl_certs_aloha directive lets HAProxy ALOHA manage SSL certificates instead of HAProxy Data Plane API.

  • Parent: dataplaneapi.resources
  • Type: boolean
  • Required: false
yaml
dataplaneapi:
  resources:
    ssl_certs_aloha: true
yaml
dataplaneapi:
  resources:
    ssl_certs_aloha: true

ssl_certs_dir Jump to heading

The resources section’s ssl_certs_dir directive sets the path to the SSL certificates directory.

  • Parent: dataplaneapi.resources
  • Type: string
  • Required: false
yaml
dataplaneapi:
  resources:
    ssl_certs_dir: /etc/haproxy/ssl
yaml
dataplaneapi:
  resources:
    ssl_certs_dir: /etc/haproxy/ssl

update_map_files Jump to heading

The resources section’s update_map_files directive enables periodically persisting runtime map values to map files.

  • Parent: dataplaneapi.resources
  • Type: boolean
  • Required: false
yaml
dataplaneapi:
  resources:
    update_map_files: false
yaml
dataplaneapi:
  resources:
    update_map_files: false

update_map_files_period Jump to heading

The resources section’s update_map_files_period directive sets the elapsed time in seconds between two maps syncing operations. Defaults to 10.

  • Parent: dataplaneapi.resources
  • Type: integer
  • Required: false
yaml
dataplaneapi:
  resources:
    update_map_files_period: 10
yaml
dataplaneapi:
  resources:
    update_map_files_period: 10

waf_dir Jump to heading

Enterprise feature

This is an enterprise feature.

The resources section’s waf_dir directive sets the path to the directory containing Web Application Firewall (WAF) files. Defaults to /etc/haproxy/waf.

  • Parent: dataplaneapi.resources
  • Type: string
  • Required: false
yaml
dataplaneapi:
  resources:
    waf_dir: /etc/hapee-3.4
yaml
dataplaneapi:
  resources:
    waf_dir: /etc/hapee-3.4

dataplaneapi.tls directives Jump to heading

HAProxy Data Plane API supports the following configuration file directives in its dataplaneapi.tls section.

tls_ca Jump to heading

The tls section’s tls_ca directive sets the path to the TLS CA certificate file used to validate client certificates during mTLS authentication.

  • Parent: dataplaneapi.tls
  • Type: string
  • Required: false
yaml
dataplaneapi:
  tls:
    tls_ca: /etc/ssl/frontends/default/ca.pem
yaml
dataplaneapi:
  tls:
    tls_ca: /etc/ssl/frontends/default/ca.pem

tls_certificate Jump to heading

The tls section’s tls_certificate directive sets the path to the TLS certificate file. This is required for HTTPS.

  • Parent: dataplaneapi.tls
  • Type: string
  • Required: false
yaml
dataplaneapi:
  tls:
    tls_certificate: /etc/haproxy/ssl/certs/server-cert.pem
yaml
dataplaneapi:
  tls:
    tls_certificate: /etc/haproxy/ssl/certs/server-cert.pem

tls_host Jump to heading

The tls section’s tls_host directive sets the host address for TLS connections. Defaults to the HTTP host.

  • Parent: dataplaneapi.tls
  • Type: string
  • Required: false
yaml
dataplaneapi:
  tls:
    tls_host: 0.0.0.0
yaml
dataplaneapi:
  tls:
    tls_host: 0.0.0.0

tls_keep_alive Jump to heading

The tls section’s tls_keep_alive directive sets the TCP keep-alive period for TLS connections. Set it to 0 to inherit the HTTP value.

  • Parent: dataplaneapi.tls
  • Type: string
  • Required: false
yaml
dataplaneapi:
  tls:
    tls_keep_alive: 1m
yaml
dataplaneapi:
  tls:
    tls_keep_alive: 1m

tls_key Jump to heading

The tls section’s tls_key directive sets the path to the TLS certificate key file. This is required for HTTPS.

  • Parent: dataplaneapi.tls
  • Type: string
  • Required: false
yaml
dataplaneapi:
  tls:
    tls_key: /etc/haproxy/ssl/certs/server-key.pem
yaml
dataplaneapi:
  tls:
    tls_key: /etc/haproxy/ssl/certs/server-key.pem

tls_listen_limit Jump to heading

The tls section’s tls_listen_limit directive sets the maximum number of simultaneous HTTPS connections. Set it to 0 to inherit the HTTP limit.

  • Parent: dataplaneapi.tls
  • Type: integer
  • Required: false
yaml
dataplaneapi:
  tls:
    tls_listen_limit: 10
yaml
dataplaneapi:
  tls:
    tls_listen_limit: 10

tls_port Jump to heading

The tls section’s tls_port directive sets the port number for HTTPS connections. Set it to 0 to select an available port.

  • Parent: dataplaneapi.tls
  • Type: integer
  • Required: false
yaml
dataplaneapi:
  tls:
    tls_port: 6443
yaml
dataplaneapi:
  tls:
    tls_port: 6443

tls_read_timeout Jump to heading

The tls section’s tls_read_timeout directive sets the read timeout for HTTPS connections. Set it to 0 to inherit the HTTP value.

  • Parent: dataplaneapi.tls
  • Type: string
  • Required: false
yaml
dataplaneapi:
  tls:
    tls_read_timeout: 10s
yaml
dataplaneapi:
  tls:
    tls_read_timeout: 10s

tls_write_timeout Jump to heading

The tls section’s tls_write_timeout directive sets the write timeout for HTTPS connections. Set it to 0 to inherit the HTTP value.

  • Parent: dataplaneapi.tls
  • Type: string
  • Required: false
yaml
dataplaneapi:
  tls:
    tls_write_timeout: 10s
yaml
dataplaneapi:
  tls:
    tls_write_timeout: 10s

dataplaneapi.transaction directives Jump to heading

HAProxy Data Plane API supports the following configuration file directives in its dataplaneapi.transaction section.

backups_dir Jump to heading

The transaction section’s backups_dir directive sets the path to directory in which to place backup files.

  • Parent: dataplaneapi.transaction
  • Type: string
  • Required: false
yaml
dataplaneapi:
  transaction:
    backups_dir: /tmp/backups
yaml
dataplaneapi:
  transaction:
    backups_dir: /tmp/backups

backups_number Jump to heading

The transaction section’s backups_number directive sets the number of backup configuration files to keep. Defaults to 0, which disables backups.

  • Parent: dataplaneapi.transaction
  • Type: integer
  • Required: false
yaml
dataplaneapi:
  transaction:
    backups_number: 10
yaml
dataplaneapi:
  transaction:
    backups_number: 10

disable_persistent_transactions Jump to heading

Enterprise feature

This is an enterprise feature.

The transaction section’s disable_persistent_transactions directive disables persisting transactions to disk.

  • Parent: dataplaneapi.transaction
  • Type: boolean
  • Required: false
yaml
dataplaneapi:
  transaction:
    disable_persistent_transactions: true
yaml
dataplaneapi:
  transaction:
    disable_persistent_transactions: true

max_open_transactions Jump to heading

The transaction section’s max_open_transactions directive limits the number of active transaction in pending state. Defaults to 20.

  • Parent: dataplaneapi.transaction
  • Type: integer
  • Required: false
yaml
dataplaneapi:
  transaction:
    max_open_transactions: 20
yaml
dataplaneapi:
  transaction:
    max_open_transactions: 20

transaction_dir Jump to heading

The transaction section’s transaction_dir directive sets the path to the directory containing transaction files. Defaults to /tmp/haproxy.

  • Parent: dataplaneapi.transaction
  • Type: string
  • Required: false
yaml
dataplaneapi:
  transaction:
    transaction_dir: /tmp/haproxy
yaml
dataplaneapi:
  transaction:
    transaction_dir: /tmp/haproxy

dataplaneapi.user directives Jump to heading

HAProxy Data Plane API supports the following configuration file directives in its dataplaneapi.user section. For an example, see Change the password.

insecure Jump to heading

The insecure field indicates whether the value of the password field will be cleartext. When true, set password to a cleartext string; when false, set password to a hash of the password.

  • Parent: dataplaneapi.user
  • Type: boolean
  • Required: false
yaml
dataplaneapi:
  user:
    - name: admin
      insecure: true
      password: adminpwd
yaml
dataplaneapi:
  user:
    - name: admin
      insecure: true
      password: adminpwd

name Jump to heading

The user name.

  • Parent: dataplaneapi.user
  • Type: string
  • Required: true
yaml
dataplaneapi:
  user:
    - name: admin
      insecure: true
      password: adminpwd
yaml
dataplaneapi:
  user:
    - name: admin
      insecure: true
      password: adminpwd

password Jump to heading

The password. When insecure is true, this is a cleartext string; when insecure is false, this is a hash of the password.

  • Parent: dataplaneapi.user
  • Type: string
  • Required: true
yaml
dataplaneapi:
  user:
    - name: admin
      insecure: false
      password: $5$s6Subz0X7FSX2zON$r94OtF6gOfWlGmySwvn3pDFIAHbIpe6mWneueqtBOm/
yaml
dataplaneapi:
  user:
    - name: admin
      insecure: false
      password: $5$s6Subz0X7FSX2zON$r94OtF6gOfWlGmySwvn3pDFIAHbIpe6mWneueqtBOm/

dataplaneapi.userlist directives Jump to heading

HAProxy Data Plane API supports the following configuration file directives in its dataplaneapi.userlist section.

userlist Jump to heading

Userlist in HAProxy configuration to use for API Basic Authentication.

  • Parent: dataplaneapi.userlist
  • Type: string
  • Required: false
yaml
dataplaneapi:
  userlist:
    userlist: dataplaneapi
yaml
dataplaneapi:
  userlist:
    userlist: dataplaneapi

userlist_file Jump to heading

Path to the configuration file that contains the userlist.

  • Parent: dataplaneapi.userlist
  • Type: string
  • Required: false
yaml
dataplaneapi:
  userlist:
    userlist_file: /etc/haproxy/haproxy.cfg
yaml
dataplaneapi:
  userlist:
    userlist_file: /etc/haproxy/haproxy.cfg

gslb directives Jump to heading

Enterprise feature

This is an enterprise feature.

This section applies to:

  • HAProxy Data Plane API 3.4 and newer

HAProxy Data Plane API supports the following configuration file directives in its gslb section. This section configures Enterprise GSLB management.

Requires the hapee-extras-gslb package. Prepare the transaction and backup directories before enabling management:

sh
sudo install -d -m 0750 /etc/hapee-extras/gslb/transactions /etc/hapee-extras/gslb/backups
sh
sudo install -d -m 0750 /etc/hapee-extras/gslb/transactions /etc/hapee-extras/gslb/backups

Example GSLB configuration:

yaml
gslb:
  config_file: /etc/hapee-extras/hapee-gslb.conf
  transaction_dir: /etc/hapee-extras/gslb/transactions
  reload_cmd: /usr/bin/systemctl reload hapee-extras-gslb
  restart_cmd: /usr/bin/systemctl restart hapee-extras-gslb
  start_cmd: /usr/bin/systemctl start hapee-extras-gslb
  stop_cmd: /usr/bin/systemctl stop hapee-extras-gslb
  validate_bin: /opt/hapee-extras/sbin/hapee-gslb
  backups_dir: /etc/hapee-extras/gslb/backups
  backups_number: 10
  disable_save_verification: false
yaml
gslb:
  config_file: /etc/hapee-extras/hapee-gslb.conf
  transaction_dir: /etc/hapee-extras/gslb/transactions
  reload_cmd: /usr/bin/systemctl reload hapee-extras-gslb
  restart_cmd: /usr/bin/systemctl restart hapee-extras-gslb
  start_cmd: /usr/bin/systemctl start hapee-extras-gslb
  stop_cmd: /usr/bin/systemctl stop hapee-extras-gslb
  validate_bin: /opt/hapee-extras/sbin/hapee-gslb
  backups_dir: /etc/hapee-extras/gslb/backups
  backups_number: 10
  disable_save_verification: false

backups_dir Jump to heading

The gslb section’s backups_dir sets the directory for storing GSLB configuration backups. Required if backups are enabled.

  • Parent: gslb
  • Type: string
  • Required: false
yaml
gslb:
  backups_dir: /etc/hapee-extras/gslb/backups
yaml
gslb:
  backups_dir: /etc/hapee-extras/gslb/backups

backups_number Jump to heading

The gslb section’s backups_number directive sets the number of backups to retain. Defaults to 0, which disables backups.

  • Parent: gslb
  • Type: integer
  • Required: false
yaml
gslb:
  backups_number: 10
yaml
gslb:
  backups_number: 10

config_file Jump to heading

The gslb section’s config_file directive sets the path to the GSLB configuration. Setting it enables GSLB management.

  • Parent: gslb
  • Type: string
  • Required: false
yaml
gslb:
  config_file: /etc/hapee-extras/hapee-gslb.conf
yaml
gslb:
  config_file: /etc/hapee-extras/hapee-gslb.conf

disable_save_verification Jump to heading

The gslb section’s disable_save_verification directive skips rendered-configuration round-trip checks. Defaults to false. Save verification is separate from transaction validation.

  • Parent: gslb
  • Type: boolean
  • Required: false
yaml
gslb:
  disable_save_verification: false
yaml
gslb:
  disable_save_verification: false

reload_cmd Jump to heading

The gslb section’s reload_cmd directive sets the command for reloading the GSLB service after committing changes. Required with the custom reload strategy.

  • Parent: gslb
  • Type: string
  • Required: false
yaml
gslb:
  reload_cmd: /usr/bin/systemctl reload hapee-extras-gslb
yaml
gslb:
  reload_cmd: /usr/bin/systemctl reload hapee-extras-gslb

restart_cmd Jump to heading

The gslb section’s restart_cmd directive sets the command for restarting the GSLB service.

  • Parent: gslb
  • Type: string
  • Required: false
yaml
gslb:
  restart_cmd: /usr/bin/systemctl restart hapee-extras-gslb
yaml
gslb:
  restart_cmd: /usr/bin/systemctl restart hapee-extras-gslb

start_cmd Jump to heading

The gslb section’s start_cmd directive sets the command for starting the GSLB service.

  • Parent: gslb
  • Type: string
  • Required: false
yaml
gslb:
  start_cmd: /usr/bin/systemctl start hapee-extras-gslb
yaml
gslb:
  start_cmd: /usr/bin/systemctl start hapee-extras-gslb

stop_cmd Jump to heading

The gslb section’s stop_cmd directive sets the command for stopping the GSLB service.

  • Parent: gslb
  • Type: string
  • Required: false
yaml
gslb:
  stop_cmd: /usr/bin/systemctl stop hapee-extras-gslb
yaml
gslb:
  stop_cmd: /usr/bin/systemctl stop hapee-extras-gslb

transaction_dir Jump to heading

The gslb section’s transaction_dir directive sets the directory for persisting GSLB transaction files. Empty uses memory-only transactions.

  • Parent: gslb
  • Type: string
  • Required: false
yaml
gslb:
  transaction_dir: /etc/hapee-extras/gslb/transactions
yaml
gslb:
  transaction_dir: /etc/hapee-extras/gslb/transactions

validate_bin Jump to heading

The gslb section’s validate_bin directive sets the binary for validating with BINARY check FILE. Takes precedence over validate_cmd.

  • Parent: gslb
  • Type: string
  • Required: false
yaml
gslb:
  validate_bin: /opt/hapee-extras/sbin/hapee-gslb
yaml
gslb:
  validate_bin: /opt/hapee-extras/sbin/hapee-gslb

validate_cmd Jump to heading

The gslb section’s validate_cmd directive sets the command for validating the GSLB configuration.

It’s a custom validator receiving GSLB_CONFIGFILE. The value doesn’t support shell quoting or expansion. Prefer validate_bin; to use this alternative, first install the script /usr/local/sbin/validate-hapee-gslb as executable:

sh
#!/bin/sh
exec /opt/hapee-extras/sbin/hapee-gslb check "${GSLB_CONFIGFILE:?}"
sh
#!/bin/sh
exec /opt/hapee-extras/sbin/hapee-gslb check "${GSLB_CONFIGFILE:?}"
  • Parent: gslb
  • Type: string
  • Required: false
yaml
gslb:
  validate_cmd: /usr/local/sbin/validate-hapee-gslb
yaml
gslb:
  validate_cmd: /usr/local/sbin/validate-hapee-gslb

haproxy directives Jump to heading

HAProxy Data Plane API supports the following configuration file directives in its haproxy section.

config_file Jump to heading

The haproxy section’s config_file directive sets the path to the HAProxy configuration file.

  • Parent: haproxy
  • Type: string
  • Required: false
yaml
haproxy:
  config_file: /etc/haproxy/haproxy.cfg
yaml
haproxy:
  config_file: /etc/haproxy/haproxy.cfg

delayed_start_max Jump to heading

The haproxy section’s delayed_start_max directive sets the maximum duration to wait for the HAProxy runtime socket to be ready.

  • Parent: haproxy
  • Type: string
  • Required: false
yaml
haproxy:
  delayed_start_max: 30s
yaml
haproxy:
  delayed_start_max: 30s

delayed_start_tick Jump to heading

The haproxy section’s delayed_start_tick directive sets the duration between checks for the HAProxy runtime socket to be ready.

  • Parent: haproxy
  • Type: string
  • Required: false
yaml
haproxy:
  delayed_start_tick: 500ms
yaml
haproxy:
  delayed_start_tick: 500ms

fid Jump to heading

The haproxy section’s fid directive sets the path to file that the HAProxy Data Plane API will use to write its ID.

  • Parent: haproxy
  • Type: string
  • Required: false
yaml
haproxy:
  fid: /etc/haproxy/fid
yaml
haproxy:
  fid: /etc/haproxy/fid

haproxy_bin Jump to heading

The haproxy section’s haproxy_bin directive sets the path to the HAProxy binary file.

  • Parent: haproxy
  • Type: string
  • Required: false
yaml
haproxy:
  haproxy_bin: /usr/local/sbin/haproxy
yaml
haproxy:
  haproxy_bin: /usr/local/sbin/haproxy

master_runtime Jump to heading

The haproxy section’s master_runtime directive sets the path to the Master Runtime API socket.

  • Parent: haproxy
  • Type: string
  • Required: false
yaml
haproxy:
  master_runtime: /var/lib/haproxy/master
yaml
haproxy:
  master_runtime: /var/lib/haproxy/master

master_worker_mode Jump to heading

The haproxy section’s master_worker_mode directive sets the flag to enable helpers when running HAProxy in master-worker mode.

  • Parent: haproxy
  • Type: boolean
  • Required: false
yaml
haproxy:
  master_worker_mode: false
yaml
haproxy:
  master_worker_mode: false

reload Jump to heading

The haproxy section’s reload directive contains settings for reloading HAProxy.

  • Parent: haproxy
  • Type: object
  • Required: false
yaml
haproxy:
  reload:
    reload_delay: 5
    reload_cmd: "systemctl reload haproxy"
    restart_cmd: "systemctl restart haproxy"
    status_cmd: "systemctl status haproxy"
    service_name: "haproxy.service"
    reload_retention: 1
    reload_strategy: custom
    validate_cmd: /usr/local/bin/validate-haproxy.sh
yaml
haproxy:
  reload:
    reload_delay: 5
    reload_cmd: "systemctl reload haproxy"
    restart_cmd: "systemctl restart haproxy"
    status_cmd: "systemctl status haproxy"
    service_name: "haproxy.service"
    reload_retention: 1
    reload_strategy: custom
    validate_cmd: /usr/local/bin/validate-haproxy.sh

haproxy.reload directives Jump to heading

HAProxy Data Plane API supports the following configuration file directives in its haproxy.reload section.

reload_cmd Jump to heading

The reload section’s reload_cmd directive sets the command for reloading HAProxy after committing changes.

  • Parent: haproxy.reload
  • Type: string
  • Required: false
yaml
haproxy:
  reload:
    reload_cmd: "systemctl reload haproxy"
yaml
haproxy:
  reload:
    reload_cmd: "systemctl reload haproxy"

reload_delay Jump to heading

The reload section’s reload_delay directive sets the minimum delay between two reloads (in seconds). Defaults to 5.

  • Parent: haproxy.reload
  • Type: integer
  • Required: false
yaml
haproxy:
  reload:
    reload_delay: 5
yaml
haproxy:
  reload:
    reload_delay: 5

reload_retention Jump to heading

The reload section’s reload_retention directive sets the number of days to retain the reload record. Defaults to 1.

  • Parent: haproxy.reload
  • Type: integer
  • Required: false
yaml
haproxy:
  reload:
    reload_retention: 1
yaml
haproxy:
  reload:
    reload_retention: 1

reload_strategy Jump to heading

The reload section’s reload_strategy directive sets the service-command defaults; it can be systemd, s6 or custom. Defaults to custom and requires reload/restart commands.

  • Parent: haproxy.reload
  • Type: string
  • Required: false
yaml
haproxy:
  reload:
    reload_strategy: custom
yaml
haproxy:
  reload:
    reload_strategy: custom

restart_cmd Jump to heading

The reload section’s restart_cmd directive sets the command to restart HAProxy.

  • Parent: haproxy.reload
  • Type: string
  • Required: false
yaml
haproxy:
  reload:
    restart_cmd: "systemctl restart haproxy"
yaml
haproxy:
  reload:
    restart_cmd: "systemctl restart haproxy"

service_name Jump to heading

The reload section’s service_name directive sets the name of the HAProxy service when deriving systemd/s6 commands.

  • Parent: haproxy.reload
  • Type: string
  • Required: false
yaml
haproxy:
  reload:
    service_name: "haproxy.service"
yaml
haproxy:
  reload:
    service_name: "haproxy.service"

start_cmd Jump to heading

Enterprise feature

This is an enterprise feature.

The reload section’s start_cmd directive sets the command to start HAProxy.

  • Parent: haproxy.reload
  • Type: string
  • Required: false
yaml
haproxy:
  reload:
    start_cmd: "/usr/bin/systemctl start hapee-3.4-lb"
yaml
haproxy:
  reload:
    start_cmd: "/usr/bin/systemctl start hapee-3.4-lb"

status_cmd Jump to heading

The reload section’s status_cmd directive sets the command for checking if HAProxy is running.

  • Parent: haproxy.reload
  • Type: string
  • Required: false
yaml
haproxy:
  reload:
    status_cmd: "systemctl status haproxy"
yaml
haproxy:
  reload:
    status_cmd: "systemctl status haproxy"

stop_cmd Jump to heading

Enterprise feature

This is an enterprise feature.

The reload section’s stop_cmd directive sets the command to stop HAProxy.

  • Parent: haproxy.reload
  • Type: string
  • Required: false
yaml
haproxy:
  reload:
    stop_cmd: "/usr/bin/systemctl stop hapee-3.4-lb"
yaml
haproxy:
  reload:
    stop_cmd: "/usr/bin/systemctl stop hapee-3.4-lb"

validate_cmd Jump to heading

The reload section’s validate_cmd directive executes a custom command to perform the HAProxy configuration check. Set it to empty to use the HAProxy binary.

  • Parent: haproxy.reload
  • Type: string
  • Required: false
yaml
haproxy:
  reload:
    validate_cmd: /usr/local/bin/validate-haproxy.sh
yaml
haproxy:
  reload:
    validate_cmd: /usr/local/bin/validate-haproxy.sh

validate_files_after Jump to heading

This section applies to:

  • HAProxy Data Plane API 3.4 and newer

The reload section’s validate_files_after directive sets a list of configuration files to be loaded after the main file for validation.

  • Parent: haproxy.reload
  • Type: string[]
  • Required: false
yaml
haproxy:
  reload:
    validate_files_after: ["/etc/haproxy/myconf1.cfg", "/etc/haproxy/myconf2.cfg"]
yaml
haproxy:
  reload:
    validate_files_after: ["/etc/haproxy/myconf1.cfg", "/etc/haproxy/myconf2.cfg"]

validate_files_before Jump to heading

This section applies to:

  • HAProxy Data Plane API 3.4 and newer

The reload section’s validate_files_before directive sets a list of configuration files to be loaded before the main file for validation.

  • Parent: haproxy.reload
  • Type: string[]
  • Required: false
yaml
haproxy:
  reload:
    validate_files_before: ["/etc/haproxy/myconf1.cfg", "/etc/haproxy/myconf2.cfg"]
yaml
haproxy:
  reload:
    validate_files_before: ["/etc/haproxy/myconf1.cfg", "/etc/haproxy/myconf2.cfg"]

keepalived directives Jump to heading

Enterprise feature

This is an enterprise feature.

This section applies to:

  • HAProxy Data Plane API 3.4 and newer

HAProxy Data Plane API supports the following configuration file directives in its keepalived section. This section configures VRRP (Keepalived) management.

It requires the hapee-extras-vrrp22 package. Prepare the transaction and backup directories before enabling management:

sh
sudo install -d -m 0750 /etc/hapee-extras/keepalived/transactions /etc/hapee-extras/keepalived/backups
sh
sudo install -d -m 0750 /etc/hapee-extras/keepalived/transactions /etc/hapee-extras/keepalived/backups

Example VRRP configuration:

yaml
keepalived:
  config_file: /etc/hapee-extras/hapee-vrrp.cfg
  start_cmd: /usr/bin/systemctl start hapee-extras-vrrp
  reload_cmd: /usr/bin/systemctl reload hapee-extras-vrrp
  restart_cmd: /usr/bin/systemctl restart hapee-extras-vrrp
  stop_cmd: /usr/bin/systemctl stop hapee-extras-vrrp
  status_cmd: /usr/bin/systemctl --quiet is-active hapee-extras-vrrp
  getpid_cmd: /usr/bin/pgrep hapee-vrrp
  signal_cmd: /bin/kill
  read_dump_cmd: /bin/cat
  validate_cmd: /bin/sh -c '/opt/hapee-extras/sbin/hapee-vrrp --config-test -f "$KEEPALIVED_TRANSACTION_FILE"'
  reload_delay: 5
  transaction_dir: /etc/hapee-extras/keepalived/transactions
  backups_dir: /etc/hapee-extras/keepalived/backups
  backups_number: 10
yaml
keepalived:
  config_file: /etc/hapee-extras/hapee-vrrp.cfg
  start_cmd: /usr/bin/systemctl start hapee-extras-vrrp
  reload_cmd: /usr/bin/systemctl reload hapee-extras-vrrp
  restart_cmd: /usr/bin/systemctl restart hapee-extras-vrrp
  stop_cmd: /usr/bin/systemctl stop hapee-extras-vrrp
  status_cmd: /usr/bin/systemctl --quiet is-active hapee-extras-vrrp
  getpid_cmd: /usr/bin/pgrep hapee-vrrp
  signal_cmd: /bin/kill
  read_dump_cmd: /bin/cat
  validate_cmd: /bin/sh -c '/opt/hapee-extras/sbin/hapee-vrrp --config-test -f "$KEEPALIVED_TRANSACTION_FILE"'
  reload_delay: 5
  transaction_dir: /etc/hapee-extras/keepalived/transactions
  backups_dir: /etc/hapee-extras/keepalived/backups
  backups_number: 10

backups_dir Jump to heading

The keepalived section’s backups_dir directive sets the directory for VRRP configuration backups.

  • Parent: keepalived
  • Type: string
  • Required: false
yaml
keepalived:
  backups_dir: /etc/hapee-extras/keepalived/backups
yaml
keepalived:
  backups_dir: /etc/hapee-extras/keepalived/backups

backups_number Jump to heading

The keepalived section’s backups_number directive sets the number of backups to retain. Defaults to 0, which disables backups.

  • Parent: keepalived
  • Type: integer
  • Required: false
yaml
keepalived:
  backups_number: 10
yaml
keepalived:
  backups_number: 10

config_file Jump to heading

The keepalived section’s config_file directive sets the VRRP configuration to manage.

  • Parent: keepalived
  • Type: string
  • Required: false
yaml
keepalived:
  config_file: /etc/hapee-extras/hapee-vrrp.cfg
yaml
keepalived:
  config_file: /etc/hapee-extras/hapee-vrrp.cfg

getpid_cmd Jump to heading

The keepalived section’s getpid_cmd directive sets the command for printing the VRRP PID. Defaults to pgrep hapee-vrrp.

  • Parent: keepalived
  • Type: string
  • Required: false
yaml
keepalived:
  getpid_cmd: /usr/bin/pgrep hapee-vrrp
yaml
keepalived:
  getpid_cmd: /usr/bin/pgrep hapee-vrrp

read_dump_cmd Jump to heading

The keepalived section’s read_dump_cmd sets the command for reading the appended state-dump file. Defaults to sudo -n cat.

  • Parent: keepalived
  • Type: string
  • Required: false
yaml
keepalived:
  read_dump_cmd: /bin/cat
yaml
keepalived:
  read_dump_cmd: /bin/cat

reload_cmd Jump to heading

The keepalived section’s reload_cmd sets the command for reloading the VRRP service after committing changes.

  • Parent: keepalived
  • Type: string
  • Required: false
yaml
keepalived:
  reload_cmd: /usr/bin/systemctl reload hapee-extras-vrrp
yaml
keepalived:
  reload_cmd: /usr/bin/systemctl reload hapee-extras-vrrp

reload_delay Jump to heading

The keepalived section’s reload_delay directive sets the reload interval in seconds. Defaults to 5, and must be positive to initialize management.

  • Parent: keepalived
  • Type: integer
  • Required: false
yaml
keepalived:
  reload_delay: 5
yaml
keepalived:
  reload_delay: 5

restart_cmd Jump to heading

The keepalived section’s restart_cmd directive sets the command for restarting the VRRP service.

  • Parent: keepalived
  • Type: string
  • Required: false
yaml
keepalived:
  restart_cmd: /usr/bin/systemctl restart hapee-extras-vrrp
yaml
keepalived:
  restart_cmd: /usr/bin/systemctl restart hapee-extras-vrrp

signal_cmd Jump to heading

The keepalived section’s signal_cmd directive sets the command for sending signals with an appended -s SIGNAL PID. Defaults to sudo -n kill.

  • Parent: keepalived
  • Type: string
  • Required: false
yaml
keepalived:
  signal_cmd: /bin/kill
yaml
keepalived:
  signal_cmd: /bin/kill

start_cmd Jump to heading

The keepalived section’s start_cmd directive sets the command for starting the VRRP service. Required when management is enabled.

  • Parent: keepalived
  • Type: string
  • Required: false
yaml
keepalived:
  start_cmd: /usr/bin/systemctl start hapee-extras-vrrp
yaml
keepalived:
  start_cmd: /usr/bin/systemctl start hapee-extras-vrrp

status_cmd Jump to heading

The keepalived section’s status_cmd directive sets the command for checking whether VRRP is running.

  • Parent: keepalived
  • Type: string
  • Required: false
yaml
keepalived:
  status_cmd: /usr/bin/systemctl --quiet is-active hapee-extras-vrrp
yaml
keepalived:
  status_cmd: /usr/bin/systemctl --quiet is-active hapee-extras-vrrp

stop_cmd Jump to heading

The keepalived section’s stop_cmd directive sets the command for stopping the VRRP service.

  • Parent: keepalived
  • Type: string
  • Required: false
yaml
keepalived:
  stop_cmd: /usr/bin/systemctl stop hapee-extras-vrrp
yaml
keepalived:
  stop_cmd: /usr/bin/systemctl stop hapee-extras-vrrp

transaction_dir Jump to heading

The keepalived section’s transaction_dir directive sets the directory containing the VRRP transaction files.

  • Parent: keepalived
  • Type: string
  • Required: false
yaml
keepalived:
  transaction_dir: /etc/hapee-extras/keepalived/transactions
yaml
keepalived:
  transaction_dir: /etc/hapee-extras/keepalived/transactions

validate_cmd Jump to heading

The keepalived section’s validate_cmd directive sets the command for validating the VRRP configuration.

It validates KEEPALIVED_TRANSACTION_FILE before commit. Keepalived validation commands support quoted arguments but don’t expand variables themselves; the example explicitly invokes /bin/sh -c to expand the environment variable. Use absolute paths, because validation receives only that environment variable.

  • Parent: keepalived
  • Type: string
  • Required: false
yaml
keepalived:
  validate_cmd: /bin/sh -c '/opt/hapee-extras/sbin/hapee-vrrp --config-test -f "$KEEPALIVED_TRANSACTION_FILE"'
yaml
keepalived:
  validate_cmd: /bin/sh -c '/opt/hapee-extras/sbin/hapee-vrrp --config-test -f "$KEEPALIVED_TRANSACTION_FILE"'

log_targets directives Jump to heading

The log_targets section lets you 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:

log_file Jump to heading

Location of the log file.

  • Parent: log_targets
  • Type: string
  • Required: false
yaml
log_targets:
  - log_to: file
    log_file: /var/log/dataplaneapi.log
    log_level: info
    log_format: text
    log_types:
      - app
yaml
log_targets:
  - log_to: file
    log_file: /var/log/dataplaneapi.log
    log_level: info
    log_format: text
    log_types:
      - app

log_format Jump to heading

Logging format, allowed values are text, JSON.

  • Parent: log_targets
  • Type: string
  • Required: false
yaml
log_targets:
  - log_to: file
    log_file: /var/log/dataplaneapi.log
    log_level: info
    log_format: text
    log_types:
      - app
yaml
log_targets:
  - log_to: file
    log_file: /var/log/dataplaneapi.log
    log_level: info
    log_format: text
    log_types:
      - app

log_level Jump to heading

Logging level, allowed values are trace, debug, info, warning, error.

  • Parent: log_targets
  • Type: string
  • Required: false
yaml
log_targets:
  - log_to: file
    log_file: /var/log/dataplaneapi.log
    log_level: info
    log_format: text
    log_types:
      - app
yaml
log_targets:
  - log_to: file
    log_file: /var/log/dataplaneapi.log
    log_level: info
    log_format: text
    log_types:
      - app

log_to Jump to heading

Log target, can be stdout, file, or syslog.

  • Parent: log_targets
  • Type: string
  • Required: false
yaml
log_targets:
  - log_to: stdout
    log_level: debug
    log_format: json
    log_types:
      - access
      - app
yaml
log_targets:
  - log_to: stdout
    log_level: debug
    log_format: json
    log_types:
      - access
      - app

log_types Jump to heading

Define which log types to log to this target, allowed values are app, access.

  • Parent: log_targets
  • Type: array of strings
  • Required: false
yaml
log_targets:
  - log_to: stdout
    log_level: debug
    log_format: json
    log_types:
      - access
      - app
yaml
log_targets:
  - log_to: stdout
    log_level: debug
    log_format: json
    log_types:
      - access
      - app

syslog_address Jump to heading

Syslog address (with port declaration in case of TCP type) where logs should be forwarded. It accepts the socket path in case of unix or unixgram.

  • Parent: log_targets
  • Type: string
  • Required: false
yaml
log_targets:
  - log_to: syslog
    log_level: info
    syslog_address: 127.0.0.1
    syslog_protocol: tcp
    syslog_tag: dataplaneapi
    syslog_level: debug
    syslog_facility: local0
    log_types:
      - access
yaml
log_targets:
  - log_to: syslog
    log_level: info
    syslog_address: 127.0.0.1
    syslog_protocol: tcp
    syslog_tag: dataplaneapi
    syslog_level: debug
    syslog_facility: local0
    log_types:
      - access

syslog_facility Jump to heading

Define the Syslog facility number, allowed values are kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron, authpriv, ftp, local0, local1, local2, local3, local4, local5, local6, local7.

  • Parent: log_targets
  • Type: string
  • Required: false
yaml
log_targets:
  - log_to: syslog
    log_level: info
    syslog_address: 127.0.0.1
    syslog_protocol: tcp
    syslog_tag: dataplaneapi
    syslog_level: debug
    syslog_facility: local0
    log_types:
      - access
yaml
log_targets:
  - log_to: syslog
    log_level: info
    syslog_address: 127.0.0.1
    syslog_protocol: tcp
    syslog_tag: dataplaneapi
    syslog_level: debug
    syslog_facility: local0
    log_types:
      - access

syslog_level Jump to heading

Define the required syslog messages level, allowed values are debug, info, notice, warning, error, critical, alert, emergency.

  • Parent: log_targets
  • Type: string
  • Required: false
yaml
log_targets:
  - log_to: syslog
    log_level: info
    syslog_address: 127.0.0.1
    syslog_protocol: tcp
    syslog_tag: dataplaneapi
    syslog_level: debug
    syslog_facility: local0
    log_types:
      - access
yaml
log_targets:
  - log_to: syslog
    log_level: info
    syslog_address: 127.0.0.1
    syslog_protocol: tcp
    syslog_tag: dataplaneapi
    syslog_level: debug
    syslog_facility: local0
    log_types:
      - access

syslog_protocol Jump to heading

Syslog server protocol, allowed values are tcp, tcp4, tcp6, unix, unixgram.

  • Parent: log_targets
  • Type: string
  • Required: false
yaml
log_targets:
  - log_to: syslog
    log_level: info
    syslog_address: 127.0.0.1
    syslog_protocol: tcp
    syslog_tag: dataplaneapi
    syslog_level: debug
    syslog_facility: local0
    log_types:
      - access
yaml
log_targets:
  - log_to: syslog
    log_level: info
    syslog_address: 127.0.0.1
    syslog_protocol: tcp
    syslog_tag: dataplaneapi
    syslog_level: debug
    syslog_facility: local0
    log_types:
      - access

syslog_tag Jump to heading

String to tag the syslog messages.

  • Parent: log_targets
  • Type: string
  • Required: false
yaml
log_targets:
  - log_to: syslog
    log_level: info
    syslog_address: 127.0.0.1
    syslog_protocol: tcp
    syslog_tag: dataplaneapi
    syslog_level: debug
    syslog_facility: local0
    log_types:
      - access
yaml
log_targets:
  - log_to: syslog
    log_level: info
    syslog_address: 127.0.0.1
    syslog_protocol: tcp
    syslog_tag: dataplaneapi
    syslog_level: debug
    syslog_facility: local0
    log_types:
      - access

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

Previous page CLI reference Next page API specifications