HAProxy Enterprise Documentation 2.5r1

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. Give each section a unique name. To apply the defaults to a frontend, backend, or listen section, use the from keyword to specify the desired defaults section name.

The fe_1 frontend takes its default settings from defaults section named http_defaults. The fe_2 frontend takes its default settings from defaults section named tcp_defaults.

defaults http_defaults
   mode http
   timeout connect 10000
   timeout client 30000
   timeout server 30000

defaults tcp_defaults
   mode tcp

frontend fe_1 from http_defaults
   bind 0.0.0.0:80

frontend fe_2 from tcp_defaults
   bind 0.0.0.0:3000
   timeout connect 20000

If a frontend, backend, or listen section does not indicate a named defaults section using the from keyword, it takes the default values specified in the nearest preceding defaults section. Relying on section ordering in this manner is not recommended, however, because it can lead to ambiguity and slow troubleshooting. Where possible, a unique name should be specified for each defaults section, and the frontend, backend, or listen sections should use the from keyword to indicate the correct defaults section.

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