Tutorials

Manage global settings

On this page

In your load balancer configuration, a global section defines settings that affect how the load balancer runs.

You can manage global settings programmatically by calling the API endpoint /services/haproxy/configuration/global.

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 global settings Jump to heading

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

nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/global"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/global"
output
json
{
  "runtime_apis": [
    {
      "level": "admin",
      "mode": "660",
      "address": "/var/run/haproxy.sock"
    }
  ],
  "insecure_fork_wanted": true,
  "master-worker": true
}
output
json
{
  "runtime_apis": [
    {
      "level": "admin",
      "mode": "660",
      "address": "/var/run/haproxy.sock"
    }
  ],
  "insecure_fork_wanted": true,
  "master-worker": true
}
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/global"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/global"
output
json
{
   "_version": 99,
   "data": {
     "runtime_apis": [
       {
         "level": "admin",
         "mode": "660",
         "address": "/var/run/haproxy.sock"
       }
     ],
     "insecure_fork_wanted": true,
     "master-worker": true
   }
}
output
json
{
   "_version": 99,
   "data": {
     "runtime_apis": [
       {
         "level": "admin",
         "mode": "660",
         "address": "/var/run/haproxy.sock"
       }
     ],
     "insecure_fork_wanted": true,
     "master-worker": true
   }
}

Replace global settings Jump to heading

To make changes to global settings, you must replace them entirely. To replace global settings, make a PUT request to the global endpoint, passing the fields in the body of the request. 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. In this example, we replace the settings to include maxconn, user, group, pidfile, and runtime_apis:

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 '{
    "maxconn": 100000,
    "chroot": "/var/empty",
    "user": "haproxy",
    "group": "haproxy",
    "pidfile": "/var/run/haproxy/haproxy.pid",
    "runtime_apis": [
      {
        "address": "/var/run/haproxy.sock",
        "level": "admin",
        "mode": "660"
      },
      {
        "address": "ipv4@0.0.0.0:9999",
        "level": "admin"
      }
    ]
  }' \
  "http://localhost:5555/v3/services/haproxy/configuration/global?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 '{
    "maxconn": 100000,
    "chroot": "/var/empty",
    "user": "haproxy",
    "group": "haproxy",
    "pidfile": "/var/run/haproxy/haproxy.pid",
    "runtime_apis": [
      {
        "address": "/var/run/haproxy.sock",
        "level": "admin",
        "mode": "660"
      },
      {
        "address": "ipv4@0.0.0.0:9999",
        "level": "admin"
      }
    ]
  }' \
  "http://localhost:5555/v3/services/haproxy/configuration/global?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 '{
    "maxconn": 100000,
    "chroot": "/var/empty",
    "user": "haproxy",
    "group": "haproxy",
    "pidfile": "/var/run/haproxy/haproxy.pid",
    "runtime_apis": [
      {
        "address": "/var/run/haproxy.sock",
        "level": "admin",
        "mode": "660"
      },
      {
        "address": "ipv4@0.0.0.0:9999",
        "level": "admin"
      }
    ]
  }' \
  "http://localhost:5555/v2/services/haproxy/configuration/global?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 '{
    "maxconn": 100000,
    "chroot": "/var/empty",
    "user": "haproxy",
    "group": "haproxy",
    "pidfile": "/var/run/haproxy/haproxy.pid",
    "runtime_apis": [
      {
        "address": "/var/run/haproxy.sock",
        "level": "admin",
        "mode": "660"
      },
      {
        "address": "ipv4@0.0.0.0:9999",
        "level": "admin"
      }
    ]
  }' \
  "http://localhost:5555/v2/services/haproxy/configuration/global?version=$CFGVER"

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

Previous page Manage backends Next page Manage default settings
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences