HAProxy Enterprise Documentation 1.6r2

Defaults

Many of the directives that you can set in a frontend, backend, or listen section can be inherited from a defaults section. By defining these settings in one place, you make it easier to change them later.

defaults
  # All sections below will inherit the settings defined here

frontend example
  # ...

backend example
  # ...

listen example
  # ...

Defaults configuration examples

In the following configuration sample, we have two frontend sections that have the same settings and point to two corresponding backends that also have the same settings.

frontend public_web_servers
   mode http
   log global
   timeout client 30s
   bind *:80
   default_backend public_web_servers

frontend api_servers
  mode http
  log global
  timeout client 30s
  bind *:8000
  default_backend api_servers

backend public_web_servers
   mode http
   balance roundrobin
   server s1 192.168.1.25:80
   server s2 192.168.1.26:80

backend api_servers
   mode http
   balance roundrobin
   server s1 192.168.1.27:8000
   server s2 192.168.1.28:8080

By adding defaults to the configuration we can define settings that all other sections below it will inherit when applicable. For instance, mode is applicable to both a frontend and a backend, but, balance only applies to backends.

defaults
   mode http
   log global
   balance roundrobin
   timeout client 30s

frontend public_web_servers
   bind *:80
   default_backend public_web_servers

frontend api_servers
  bind *:8000
  default_backend api_servers

backend public_web_servers
   server s1 192.168.1.25:80
   server s2 192.168.1.26:80

backend api_servers
   server s1 192.168.1.27:8000
   server s2 192.168.1.28:8080

Overriding a defaults section

Each following frontend, backend, or listen section after a defaults section can still override a setting that was inherited. Building from the previous configuration sample, we have added a frontend and backend that load balance MySQL database instances.

MySQL databases don't communicate over HTTP and do better with least connections load-balancing, so the mode and balance directives have been added to override the settings defined in defaults.

defaults
   mode http
   log global
   balance roundrobin
   timeout client 30s

frontend public_web_servers
   bind *:80
   default_backend public_web_servers

frontend api_servers
  bind *:8000
  default_backend api_servers

backend public_web_servers
   server s1 192.168.1.25:80
   server s2 192.168.1.26:80

backend api_servers
   server s1 192.168.1.27:8000
   server s2 192.168.1.28:8080

frontend mysql
   # Overriding the mode defined on defaults
   mode tcp
   bind *:3306
   default_backend mysql_servers

backend mysql_servers
   # Overriding the load-balancing algorithm defined on defaults
   balance leastconn
   server s1 192.168.1.29:3306
   server s2 192.168.1.30:3306

Defining multiple defaults sections

You may define more than one defaults section. Each one applies to any frontend, backend, or listen sections that follow it. However, if you define another defaults section, it will not inherit settings from a previous defaults section.

defaults
   mode http
   log global
   balance roundrobin
   timeout client 30s

frontend public_web_servers
   bind *:80
   default_backend public_web_servers

frontend api_servers
  bind *:8000
  default_backend api_servers

backend public_web_servers
   server s1 192.168.1.25:80
   server s2 192.168.1.26:80

backend api_servers
   server s1 192.168.1.27:8000
   server s2 192.168.1.28:8080

defaults
   # Setting new defaults for all sections below
   # Warning, settings from previous defaults sections are not inherited and
   # need to be defined again if needed.

   mode tcp
   log global
   balance leastconn
   timeout client 30s

frontend mysql
   bind *:3306
   default_backend mysql_servers

backend mysql_servers
   server s1 192.168.1.29:3306
   server s2 192.168.1.30:3306

Data Plane API

Install the Data Plane API.

You can manage the global section of your configuration remotely by calling the Data Plane API endpoint /services/haproxy/configuration/defaults.

Get the contents of a defaults section with the GET method:

$ curl -X GET \
    --user admin:adminpwd \
    "http://127.0.0.1:5555/v2/services/haproxy/configuration/defaults"

# output
{
   "_version":5,
   "data":{
      "error_files":null,
      "client_timeout":30000,
      "connect_timeout":10000,
      "dontlognull":"enabled",
      "forwardfor":{
         "enabled":"enabled",
         "except":"127.0.0.0/8"
      },
      "httplog":true,
      "mode":"http",
      "redispatch":{
         "enabled":"enabled"
      },
      "retries":3,
      "server_timeout":30000
   }
}

Replace the contents of a defaults section with the PUT method:

$ curl -X PUT \
    --user admin:adminpwd \
    -H "Content-Type: application/json" \
    -d '{
      "error_files":null,
      "client_timeout":10000,
      "connect_timeout":5000,
      "dontlognull":"enabled",
      "forwardfor":{
         "enabled":"enabled",
         "except":"127.0.0.0/8"
      },
      "httplog":true,
      "mode":"http",
      "redispatch":{
         "enabled":"enabled"
      },
      "retries":3,
      "server_timeout":10000
    }' \
    "http://127.0.0.1:5555/v2/services/haproxy/configuration/defaults?version=2"

Next up

Userlist