HAProxy Enterprise

Manage GSLB

Availability:

  • Available in HAProxy Enterprise Data Plane API 3.4 and newer
  • Available in the HAProxy Data Plane API on HAProxy ALOHA 18.5 and newer
  • Not available in the community edition of HAProxy Data Plane API

Running HAProxy ALOHA?

GSLB is already configured in the ALOHA firmware, so you can skip the setup steps. See Manage GSLB on HAProxy ALOHA.

Overview Jump to heading

HAProxy Data Plane API can manage the configuration of the HAProxy Enterprise Global Server Load Balancing (GSLB) module. Once you enable it, you can:

  • read and change zones, records, answer lists, answer records, and GeoIP maps through the /services/gslb API endpoints.
  • group changes into transactions and validate every change before it’s applied.
  • reload the GSLB service automatically.

This tutorial shows you how to enable the feature in the gslb section of the Data Plane API configuration file, and then how to read and change zones, records, answer lists, and GeoIP maps with API calls.

How GSLB management works Jump to heading

When the gslb.config_file option is set, HAProxy Data Plane API:

  1. Parses the GSLB configuration file and exposes it through the /services/gslb/configuration endpoints.
  2. Applies each change either directly or inside a transaction. Before saving, it reads the new configuration back to make sure the change was written correctly, unless you turn that check off with disable_save_verification.
  3. Validates the resulting configuration file with validate_bin or validate_cmd. If validation fails, the API answers 400 Bad Request and leaves the active configuration untouched.
  4. Replaces the configuration file, optionally keeps a copy of the previous version in backups_dir, and reloads the GSLB service with reload_cmd.

When gslb.config_file isn’t set, the /services/gslb endpoints respond with 501 Not Implemented.

Every change is validated with the module’s own checker, backed up, and applied with a reload, so a mistake is refused with a reason instead of reaching production DNS.

Tip

If you’re making a one-off edit to a small template, it’s simpler to change /etc/hapee-extras/hapee-gslb.conf and reload the service. The API manages that same file. It doesn’t replace the GSLB module, its package, or the GSLB configuration itself.

Important to know Jump to heading

  • The GSLB service runs under the same init system as HAProxy Enterprise. If you don’t set the service commands, the API derives them from haproxy.reload.reload_strategy as follows:

    Reload strategy Default commands
    systemd sudo -n systemctl reload hapee-extras-gslb.service, and the matching restart, start, and stop commands.
    s6 s6-svc -2 /var/run/s6/services/hapee-extras-gslb, and the matching -r, -u, and -d commands.
    custom No defaults. You must set reload_cmd, otherwise HAProxy Data Plane API won’t start.
  • GSLB reloads use the reload_delay and reload_retention values from the haproxy.reload section.

  • If the API can’t initialize GSLB management, for example, because it can’t create transaction_dir, it logs an error and disables only GSLB management. The rest of the API keeps running, and the /services/gslb endpoints respond with 501 Not Implemented. Check the API logs if the endpoints don’t respond as expected.

  • validate_bin and validate_cmd both check a candidate configuration before the API writes it. Use whichever matches the tooling you have, and note that validate_bin runs when both are set.

  • validate_bin is a program. The API runs it as <validate_bin> check <file>: the word check, then the path of the candidate file. The packaged /opt/hapee-extras/gslb/scripts/gslb-wrapper.sh is the checker the GSLB service itself uses, and it takes exactly those arguments.

  • validate_cmd is a command line for a script of your own. The API sets the GSLB_CONFIGFILE environment variable to the path of the candidate file, and the command can read it. The command doesn’t run through a shell and is split on whitespace, so quotes aren’t interpreted and $GSLB_CONFIGFILE isn’t expanded in its arguments. Read the variable inside the script instead.

  • If you set backups_number to a value greater than 0, you must also set backups_dir. Otherwise, GSLB management is disabled.

  • Always set transaction_dir. With it, in-progress transactions survive a restart of the API. Without it, the API keeps them in memory, and GSLB management can fail to initialize when HAProxy exposes a runtime socket, which leaves the /services/gslb endpoints answering 501 Not Implemented. If they do, check this option first.

Install and configure Jump to heading

Install the module and enable API management before you make any API calls. This section covers how to enable management, the configuration version you must send with every change, and how the API reports the result of a change.

Enable GSLB management Jump to heading

To enable GSLB management in HAProxy Data Plane API:

  1. Install and configure the GSLB module as described in Global Server Load Balancing. Make sure the hapee-extras-gslb service is running.

  2. Edit /etc/hapee-extras/dataplaneapi.yml and add a gslb section at the top level of the file:

    The dataplaneapi.yml packaged with Data Plane API already contains the section:

    dataplaneapi.yml
    yaml
    gslb:
    config_file: /etc/hapee-extras/hapee-gslb.conf
    transaction_dir: /tmp/gslb/transactions
    reload_cmd: /usr/bin/systemctl reload hapee-extras-gslb.service
    restart_cmd: /usr/bin/systemctl restart hapee-extras-gslb.service
    start_cmd: /usr/bin/systemctl start hapee-extras-gslb.service
    stop_cmd: /usr/bin/systemctl stop hapee-extras-gslb.service
    validate_bin: null
    validate_cmd: /opt/hapee-extras/gslb/scripts/gslb-wrapper.sh check
    backups_dir: /etc/gslb/backups
    backups_number: 10
    dataplaneapi.yml
    yaml
    gslb:
    config_file: /etc/hapee-extras/hapee-gslb.conf
    transaction_dir: /tmp/gslb/transactions
    reload_cmd: /usr/bin/systemctl reload hapee-extras-gslb.service
    restart_cmd: /usr/bin/systemctl restart hapee-extras-gslb.service
    start_cmd: /usr/bin/systemctl start hapee-extras-gslb.service
    stop_cmd: /usr/bin/systemctl stop hapee-extras-gslb.service
    validate_bin: null
    validate_cmd: /opt/hapee-extras/gslb/scripts/gslb-wrapper.sh check
    backups_dir: /etc/gslb/backups
    backups_number: 10

    In this example:

    • config_file points to the GSLB configuration file. Setting it enables the /services/gslb endpoints.
    • reload_cmd, restart_cmd, start_cmd, and stop_cmd control the hapee-extras-gslb.service unit through systemd. The API needs them when haproxy.reload.reload_strategy is custom.
    • validate_cmd runs the module’s checker on each candidate configuration, so what you validate is what the GSLB service will load.
    • transaction_dir stores in-progress transactions on disk. The API creates the directory if it doesn’t exist.
    • backups_dir and backups_number keep the last 10 committed configurations.
  3. Optional: To validate with a script of your own instead, set validate_cmd to it. The API sets the GSLB_CONFIGFILE environment variable to the path of the file to validate:

    dataplaneapi.yml
    yaml
    gslb:
    config_file: /etc/hapee-extras/hapee-gslb.conf
    validate_cmd: /usr/local/bin/validate-gslb.sh
    dataplaneapi.yml
    yaml
    gslb:
    config_file: /etc/hapee-extras/hapee-gslb.conf
    validate_cmd: /usr/local/bin/validate-gslb.sh
    validate-gslb.sh
    sh
    #!/bin/sh
    exec /opt/hapee-extras/gslb/scripts/gslb-wrapper.sh check "$GSLB_CONFIGFILE"
    validate-gslb.sh
    sh
    #!/bin/sh
    exec /opt/hapee-extras/gslb/scripts/gslb-wrapper.sh check "$GSLB_CONFIGFILE"

    The script must exit with a non-zero code when the configuration is invalid. The API returns the script’s output in the error response.

  4. Restart HAProxy Data Plane API:

    sh
    sudo systemctl restart hapee-extras-dataplaneapi
    sh
    sudo systemctl restart hapee-extras-dataplaneapi
  5. Verify that the API can read the GSLB configuration:

    sh
    curl --request GET \
    --user admin:adminpwd \
    "http://127.0.0.1:5555/v3/services/gslb/configuration/zones"
    sh
    curl --request GET \
    --user admin:adminpwd \
    "http://127.0.0.1:5555/v3/services/gslb/configuration/zones"
    output
    json
    [
    {
    "name": "example.com",
    "records": [
    { "index": 0, "name": "@", "params": { "type": "SOA", "primary_master": "ns1", "serial": 1 } }
    ],
    "ttl": 3600
    }
    ]
    output
    json
    [
    {
    "name": "example.com",
    "records": [
    { "index": 0, "name": "@", "params": { "type": "SOA", "primary_master": "ns1", "serial": 1 } }
    ],
    "ttl": 3600
    }
    ]

Tip

You can set every option in this section from the command line instead, by prefixing its name with --gslb- and replacing underscores with dashes. For example, --gslb-config-file. A command-line argument takes precedence over the configuration file. See the CLI reference.

Disable save verification Jump to heading

By default, before saving any change, the API renders the new configuration and reads it back to make sure the change was written correctly. If it wasn’t, the API returns an error instead of writing a file the GSLB service can’t load.

This check renders and parses the whole configuration on every create, edit, and delete, so its cost grows with the size of the configuration. If you manage a very large configuration and accept the risk, you can turn off this validation and verification:

dataplaneapi.yml
yaml
gslb:
config_file: /etc/hapee-extras/hapee-gslb.conf
disable_save_verification: true
dataplaneapi.yml
yaml
gslb:
config_file: /etc/hapee-extras/hapee-gslb.conf
disable_save_verification: true

Get the configuration version Jump to heading

You must send the current configuration version with every change, either in the version parameter or by using a transaction. The API uses the version for optimistic concurrency control, so if someone else has changed the configuration since you read it, your write is rejected instead of overwriting their change.

GSLB keeps its own version, separate from the HAProxy configuration version. Read it from the GSLB version endpoint before each write:

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

The value increments with every write, so you must read it again before your next change. If you send a stale value, the API refuses your change with 409 version mismatch.

Response codes and reloads Jump to heading

Inside a transaction, a change is written to the transaction instead of the configuration file, so nothing reaches the file until you commit, and the commit answers 202 Accepted.

When a change needs a reload, the API applies it in the background. By default it writes your change, schedules the reload, and answers 202 Accepted with a Reload-ID header:

output
text
HTTP 202 Accepted
Reload-ID: 2026-10-29-0
output
text
HTTP 202 Accepted
Reload-ID: 2026-10-29-0

To wait for the reload before returning, add force_reload=true to the request. The status code then reports the outcome directly, and no reload ID comes back:

Request Default With force_reload=true
POST, to create 202 Accepted 201 Created
PUT, to replace 202 Accepted 200 OK
DELETE 202 Accepted 204 No Content

The code reflects what the request did: a create answers 201 Created because it made a resource, a replace answers 200 OK because it changed an existing one, and a delete answers 204 No Content because there is nothing left to return.

Some changes, such as adding a server to a backend, are applied through the HAProxy Runtime API instead of a reload. Those answer 201 Created without waiting for a reload.

To follow a scheduled reload, you can pass the ID from the Reload-ID header to the reloads endpoint of the service:

nix
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/haproxy/reloads/2026-10-29-0"
nix
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/haproxy/reloads/2026-10-29-0"
output
json
{
"id": "2026-10-29-0",
"reload_timestamp": 1793301215,
"status": "succeeded"
}
output
json
{
"id": "2026-10-29-0",
"reload_timestamp": 1793301215,
"status": "succeeded"
}

The reloads endpoints are /services/haproxy/reloads, /services/keepalived/reloads, and /services/gslb/reloads, each with an /{id} variant. Inside a transaction, a change is written to the transaction instead of the configuration file, which means nothing reaches the file until you commit, and the commit returns 202 Accepted.

Tasks Jump to heading

Once management is enabled, use these requests to read and change the configuration.

List a specific zone Jump to heading

To read a specific zone, you can specify its name in the GET call to the zones endpoint.

nix
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/gslb/configuration/zones/example.com"
nix
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/gslb/configuration/zones/example.com"
output
json
{
"name": "example.com",
"records": [
{
"index": 0,
"name": "@",
"ttl": 900,
"params": {
"type": "SOA",
"primary_master": "ns1",
"mail": "hostmaster",
"serial": 1
}
},
{
"index": 1,
"name": "@",
"params": { "type": "NS", "hostname": "ns1" }
},
{
"index": 2,
"name": "ns1",
"params": { "type": "A", "ipv4_address": "203.0.113.1" }
}
],
"ttl": 3600
}
output
json
{
"name": "example.com",
"records": [
{
"index": 0,
"name": "@",
"ttl": 900,
"params": {
"type": "SOA",
"primary_master": "ns1",
"mail": "hostmaster",
"serial": 1
}
},
{
"index": 1,
"name": "@",
"params": { "type": "NS", "hostname": "ns1" }
},
{
"index": 2,
"name": "ns1",
"params": { "type": "A", "ipv4_address": "203.0.113.1" }
}
],
"ttl": 3600
}

Add a zone Jump to heading

Add a zone by making a POST request to the zones endpoint, sending the zone and its records in the body of the request. Note that prior to making the POST 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/gslb/configuration/version)
curl --request POST \
--user admin:adminpwd \
--header "Content-Type: application/json" \
-d '{
"name": "other.example.net",
"ttl": 600,
"records": [
{
"name": "@",
"params": {
"type": "SOA",
"primary_master": "ns1.other.example.net.",
"mail": "admin.other.example.net.",
"serial": 1,
"refresh": 7200,
"retry": 1800,
"expire": 259200,
"ncache": 900
}
},
{
"name": "@",
"params": {
"type": "NS",
"hostname": "ns1.other.example.net."
}
},
{
"name": "ns1",
"params": {
"type": "A",
"ipv4_address": "203.0.113.9"
}
}
]
}' \
"http://localhost:5555/v3/services/gslb/configuration/zones?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/gslb/configuration/version)
curl --request POST \
--user admin:adminpwd \
--header "Content-Type: application/json" \
-d '{
"name": "other.example.net",
"ttl": 600,
"records": [
{
"name": "@",
"params": {
"type": "SOA",
"primary_master": "ns1.other.example.net.",
"mail": "admin.other.example.net.",
"serial": 1,
"refresh": 7200,
"retry": 1800,
"expire": 259200,
"ncache": 900
}
},
{
"name": "@",
"params": {
"type": "NS",
"hostname": "ns1.other.example.net."
}
},
{
"name": "ns1",
"params": {
"type": "A",
"ipv4_address": "203.0.113.9"
}
}
]
}' \
"http://localhost:5555/v3/services/gslb/configuration/zones?version=$CFGVER"
output
text
HTTP 202
output
text
HTTP 202

By default, the API applies the change in the background: it answers 202 Accepted with a Reload-ID header, rewrites the configuration file with the new zone, and keeps the previous version in backups_dir. The version increments with every write, so you must read it again before the next change.

To wait for the reload instead of letting it run in the background, add force_reload=true to the query string. The same request then answers 201 Created. The delete example shows the parameter in place.

Keep these things in mind

  • Every zone needs its own SOA and NS records. A zone without an SOA is refused with error: Zone '...' has no SOA record.
  • A new zone must not overlap an existing one. Adding added.example.com while example.com is served returns 400 Bad Request with error: Zone 'added.example.com.' is a super-zone of one or more existing zones.
  • Records that name another host need a trailing dot. ns1.other.example.net without the dot is written into the template as a relative name and is served as ns1.other.example.net.other.example.net.. Write ns1.other.example.net., or a short relative name such as ns1.

List zones Jump to heading

To list the zones, make a GET request to the zones endpoint.

nix
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/gslb/configuration/zones"
nix
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/gslb/configuration/zones"
output
json
[
{
"name": "example.com",
"ttl": 3600,
"records": [
{
"index": 0,
"name": "@",
"ttl": 900,
"params": {
"type": "SOA",
"primary_master": "ns1",
"mail": "hostmaster",
"serial": 1
}
},
{
"index": 1,
"name": "ns1",
"params": {
"type": "A",
"ipv4_address": "203.0.113.1"
}
}
]
},
{
"name": "other.example.net",
"ttl": 600,
"records": [
{
"name": "@",
"params": {
"type": "SOA",
"primary_master": "ns1.other.example.net.",
"mail": "admin.other.example.net.",
"serial": 1,
"refresh": 7200,
"retry": 1800,
"expire": 259200,
"ncache": 900
}
},
{
"name": "@",
"params": {
"type": "NS",
"hostname": "ns1.other.example.net."
}
},
{
"name": "ns1",
"params": {
"type": "A",
"ipv4_address": "203.0.113.9"
}
}
]
}
]
output
json
[
{
"name": "example.com",
"ttl": 3600,
"records": [
{
"index": 0,
"name": "@",
"ttl": 900,
"params": {
"type": "SOA",
"primary_master": "ns1",
"mail": "hostmaster",
"serial": 1
}
},
{
"index": 1,
"name": "ns1",
"params": {
"type": "A",
"ipv4_address": "203.0.113.1"
}
}
]
},
{
"name": "other.example.net",
"ttl": 600,
"records": [
{
"name": "@",
"params": {
"type": "SOA",
"primary_master": "ns1.other.example.net.",
"mail": "admin.other.example.net.",
"serial": 1,
"refresh": 7200,
"retry": 1800,
"expire": 259200,
"ncache": 900
}
},
{
"name": "@",
"params": {
"type": "NS",
"hostname": "ns1.other.example.net."
}
},
{
"name": "ns1",
"params": {
"type": "A",
"ipv4_address": "203.0.113.9"
}
}
]
}
]

Replace a zone Jump to heading

To change a zone, replace it entirely by making a PUT request to the zones endpoint with the zone name in the path. Send the whole zone again, with your changes applied; this example moves the address in the ns1 record and raises the TTL.

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/gslb/configuration/version)
curl --request PUT \
--user admin:adminpwd \
--header "Content-Type: application/json" \
-d '{
"name": "other.example.net",
"ttl": 900,
"records": [
{
"name": "@",
"params": {
"type": "SOA",
"primary_master": "ns1.other.example.net.",
"mail": "admin.other.example.net.",
"serial": 2,
"refresh": 7200,
"retry": 1800,
"expire": 259200,
"ncache": 900
}
},
{
"name": "@",
"params": {
"type": "NS",
"hostname": "ns1.other.example.net."
}
},
{
"name": "ns1",
"params": {
"type": "A",
"ipv4_address": "203.0.113.10"
}
}
]
}' \
"http://localhost:5555/v3/services/gslb/configuration/zones/other.example.net?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/gslb/configuration/version)
curl --request PUT \
--user admin:adminpwd \
--header "Content-Type: application/json" \
-d '{
"name": "other.example.net",
"ttl": 900,
"records": [
{
"name": "@",
"params": {
"type": "SOA",
"primary_master": "ns1.other.example.net.",
"mail": "admin.other.example.net.",
"serial": 2,
"refresh": 7200,
"retry": 1800,
"expire": 259200,
"ncache": 900
}
},
{
"name": "@",
"params": {
"type": "NS",
"hostname": "ns1.other.example.net."
}
},
{
"name": "ns1",
"params": {
"type": "A",
"ipv4_address": "203.0.113.10"
}
}
]
}' \
"http://localhost:5555/v3/services/gslb/configuration/zones/other.example.net?version=$CFGVER"
output
text
HTTP 202
output
text
HTTP 202

As with a create, the default answer is 202 Accepted, or 200 OK with force_reload=true, because a replace changes an existing resource.

Delete a zone Jump to heading

To delete a zone, make a DELETE request to the zones endpoint with the zone name in the path.

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/gslb/configuration/version)
curl --request DELETE \
--user admin:adminpwd \
"http://localhost:5555/v3/services/gslb/configuration/zones/other.example.net?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/gslb/configuration/version)
curl --request DELETE \
--user admin:adminpwd \
"http://localhost:5555/v3/services/gslb/configuration/zones/other.example.net?version=$CFGVER"
output
text
HTTP 202
output
text
HTTP 202

Add force_reload=true to wait for the reload:

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/gslb/configuration/version)
curl --request DELETE \
--user admin:adminpwd \
"http://localhost:5555/v3/services/gslb/configuration/zones/other.example.net?version=$CFGVER&force_reload=true"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/gslb/configuration/version)
curl --request DELETE \
--user admin:adminpwd \
"http://localhost:5555/v3/services/gslb/configuration/zones/other.example.net?version=$CFGVER&force_reload=true"
output
text
HTTP 204
output
text
HTTP 204

The default answer is 202 Accepted, or 204 No Content with force_reload=true, because a delete leaves nothing to return.

Verify that the new name is served Jump to heading

The API validated the change and wrote the file, but the GSLB service applies it when it reloads. Ask the service directly to see what DNS actually answers. The default listener configuration includes 127.0.0.1:153 for exactly this check.

sh
dig @127.0.0.1 -p 153 ns1.other.example.net A +short
sh
dig @127.0.0.1 -p 153 ns1.other.example.net A +short
output
text
203.0.113.9
output
text
203.0.113.9

If the name is missing, the service has not picked up the change, or its reload command does not match the init system. See the reload strategy table in Important to know.

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