Tutorials

Manage default settings

On this page

In your load balancer configuration, a defaults section defines settings that apply when a frontend, backend, or listen section that follows it doesn’t set those same settings. It offers a way to store common settings in one place.

In APIv2, there was only one, non-named defaults section that you could modify via the defaults endpoint, or use the named_defaults endpoint to modify defaults sections that had names. In APIv3, the defaults endpoint returns the named and non-named endpoints together, giving the non-named ones generic names.

Getting and setting the version parameter Jump to heading

When making a POST, PUT, or DELETE API call, you must add the version URL parameter. For example:

nix
http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=1
nix
http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=1

The version parameter must match the load balancer’s current configuration version. This is because the Data Plane API uses optimistic concurrency control, or optimistic locking, to manage its transactions. This ensures that if multiple entities modify a resource that the changes are applied correctly. The APIv3 examples in this section make a GET request to /v3/services/haproxy/configuration/version immediately before making a call to update a resource to retrieve the version and populate the CFGVER environment variable for the URL version parameter as is shown in the following command:

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)

You will then use the value of the environment variable to populate the version parameter in the endpoint URL. An example URL may look like this. Note the environment variable reference, $CFGVER:

nix
http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=$CFGVER
nix
http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=$CFGVER

List defaults Jump to heading

To get the contents of a defaults section, make a GET request to the defaults endpoint:

nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/defaults"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/defaults"
output
json
[
  {
    "client_timeout": 600000,
    "connect_timeout": 600000,
    "dontlognull": "enabled",
    "httplog": true,
    "mode": "http",
    "name": "unnamed_defaults_1",
    "redispatch": {
      "enabled": "enabled"
    },
    "retries": 3,
    "server_timeout": 600000
  }
]
output
json
[
  {
    "client_timeout": 600000,
    "connect_timeout": 600000,
    "dontlognull": "enabled",
    "httplog": true,
    "mode": "http",
    "name": "unnamed_defaults_1",
    "redispatch": {
      "enabled": "enabled"
    },
    "retries": 3,
    "server_timeout": 600000
  }
]
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/defaults"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/defaults"
output
json
{
   "_version": 99,
   "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
   }
}
output
json
{
   "_version": 99,
   "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 defaults Jump to heading

To make changes to a defaults section, you must replace its contents entirely. To replace a defaults section, make a PUT request to the defaults endpoint, passing the name of the defaults section at the end of the URL path. Note that prior to making the PUT request, you must first capture the current version in an environment variable (CFGVER in this example) and use the value in your request:

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
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://localhost:5555/v3/services/haproxy/configuration/defaults/unnamed_defaults_1?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
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://localhost:5555/v3/services/haproxy/configuration/defaults/unnamed_defaults_1?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
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://localhost:5555/v2/services/haproxy/configuration/defaults?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
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://localhost:5555/v2/services/haproxy/configuration/defaults?version=$CFGVER"

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

Previous page Manage global settings Next page Manage SSL/TLS certificates
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences