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/gslbAPI 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:
- Parses the GSLB configuration file and exposes it through the
/services/gslb/configurationendpoints. - 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. - Validates the resulting configuration file with
validate_binorvalidate_cmd. If validation fails, the API answers400 Bad Requestand leaves the active configuration untouched. - Replaces the configuration file, optionally keeps a copy of the previous version in
backups_dir, and reloads the GSLB service withreload_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_strategyas follows:Reload strategy Default commands systemdsudo -n systemctl reload hapee-extras-gslb.service, and the matchingrestart,start, andstopcommands.s6s6-svc -2 /var/run/s6/services/hapee-extras-gslb, and the matching-r,-u, and-dcommands.customNo defaults. You must set reload_cmd, otherwise HAProxy Data Plane API won’t start. -
GSLB reloads use the
reload_delayandreload_retentionvalues from thehaproxy.reloadsection. -
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/gslbendpoints respond with501 Not Implemented. Check the API logs if the endpoints don’t respond as expected. -
validate_binandvalidate_cmdboth check a candidate configuration before the API writes it. Use whichever matches the tooling you have, and note thatvalidate_binruns when both are set. -
validate_binis a program. The API runs it as<validate_bin> check <file>: the wordcheck, then the path of the candidate file. The packaged/opt/hapee-extras/gslb/scripts/gslb-wrapper.shis the checker the GSLB service itself uses, and it takes exactly those arguments. -
validate_cmdis a command line for a script of your own. The API sets theGSLB_CONFIGFILEenvironment 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_CONFIGFILEisn’t expanded in its arguments. Read the variable inside the script instead. -
If you set
backups_numberto a value greater than0, you must also setbackups_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/gslbendpoints answering501 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:
-
Install and configure the GSLB module as described in Global Server Load Balancing. Make sure the
hapee-extras-gslbservice is running. -
Edit
/etc/hapee-extras/dataplaneapi.ymland add agslbsection at the top level of the file:The
dataplaneapi.ymlpackaged with Data Plane API already contains the section:dataplaneapi.ymlyamlgslb:config_file: /etc/hapee-extras/hapee-gslb.conftransaction_dir: /tmp/gslb/transactionsreload_cmd: /usr/bin/systemctl reload hapee-extras-gslb.servicerestart_cmd: /usr/bin/systemctl restart hapee-extras-gslb.servicestart_cmd: /usr/bin/systemctl start hapee-extras-gslb.servicestop_cmd: /usr/bin/systemctl stop hapee-extras-gslb.servicevalidate_bin: nullvalidate_cmd: /opt/hapee-extras/gslb/scripts/gslb-wrapper.sh checkbackups_dir: /etc/gslb/backupsbackups_number: 10dataplaneapi.ymlyamlgslb:config_file: /etc/hapee-extras/hapee-gslb.conftransaction_dir: /tmp/gslb/transactionsreload_cmd: /usr/bin/systemctl reload hapee-extras-gslb.servicerestart_cmd: /usr/bin/systemctl restart hapee-extras-gslb.servicestart_cmd: /usr/bin/systemctl start hapee-extras-gslb.servicestop_cmd: /usr/bin/systemctl stop hapee-extras-gslb.servicevalidate_bin: nullvalidate_cmd: /opt/hapee-extras/gslb/scripts/gslb-wrapper.sh checkbackups_dir: /etc/gslb/backupsbackups_number: 10In this example:
config_filepoints to the GSLB configuration file. Setting it enables the/services/gslbendpoints.reload_cmd,restart_cmd,start_cmd, andstop_cmdcontrol thehapee-extras-gslb.serviceunit through systemd. The API needs them whenhaproxy.reload.reload_strategyiscustom.validate_cmdruns the module’s checker on each candidate configuration, so what you validate is what the GSLB service will load.transaction_dirstores in-progress transactions on disk. The API creates the directory if it doesn’t exist.backups_dirandbackups_numberkeep the last 10 committed configurations.
-
Optional: To validate with a script of your own instead, set
validate_cmdto it. The API sets theGSLB_CONFIGFILEenvironment variable to the path of the file to validate:dataplaneapi.ymlyamlgslb:config_file: /etc/hapee-extras/hapee-gslb.confvalidate_cmd: /usr/local/bin/validate-gslb.shdataplaneapi.ymlyamlgslb:config_file: /etc/hapee-extras/hapee-gslb.confvalidate_cmd: /usr/local/bin/validate-gslb.shvalidate-gslb.shsh#!/bin/shexec /opt/hapee-extras/gslb/scripts/gslb-wrapper.sh check "$GSLB_CONFIGFILE"validate-gslb.shsh#!/bin/shexec /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.
-
Restart HAProxy Data Plane API:
shsudo systemctl restart hapee-extras-dataplaneapishsudo systemctl restart hapee-extras-dataplaneapi -
Verify that the API can read the GSLB configuration:
shcurl --request GET \--user admin:adminpwd \"http://127.0.0.1:5555/v3/services/gslb/configuration/zones"shcurl --request GET \--user admin:adminpwd \"http://127.0.0.1:5555/v3/services/gslb/configuration/zones"outputjson[{"name": "example.com","records": [{ "index": 0, "name": "@", "params": { "type": "SOA", "primary_master": "ns1", "serial": 1 } }],"ttl": 3600}]outputjson[{"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.ymlyamlgslb:config_file: /etc/hapee-extras/hapee-gslb.confdisable_save_verification: true
dataplaneapi.ymlyamlgslb:config_file: /etc/hapee-extras/hapee-gslb.confdisable_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:
nixCFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/gslb/configuration/version)
nixCFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/gslb/configuration/version)
outputtext11
outputtext11
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:
outputtextHTTP 202 AcceptedReload-ID: 2026-10-29-0
outputtextHTTP 202 AcceptedReload-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:
nixcurl --request GET \--user admin:adminpwd \"http://localhost:5555/v3/services/haproxy/reloads/2026-10-29-0"
nixcurl --request GET \--user admin:adminpwd \"http://localhost:5555/v3/services/haproxy/reloads/2026-10-29-0"
outputjson{"id": "2026-10-29-0","reload_timestamp": 1793301215,"status": "succeeded"}
outputjson{"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.
nixcurl --request GET \--user admin:adminpwd \"http://localhost:5555/v3/services/gslb/configuration/zones/example.com"
nixcurl --request GET \--user admin:adminpwd \"http://localhost:5555/v3/services/gslb/configuration/zones/example.com"
outputjson{"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}
outputjson{"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:
nixCFGVER=$(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"
nixCFGVER=$(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"
outputtextHTTP 202
outputtextHTTP 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.comwhileexample.comis served returns400 Bad Requestwitherror: 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.netwithout the dot is written into the template as a relative name and is served asns1.other.example.net.other.example.net.. Writens1.other.example.net., or a short relative name such asns1.
List zones Jump to heading
To list the zones, make a GET request to the zones endpoint.
nixcurl --request GET \--user admin:adminpwd \"http://localhost:5555/v3/services/gslb/configuration/zones"
nixcurl --request GET \--user admin:adminpwd \"http://localhost:5555/v3/services/gslb/configuration/zones"
outputjson[{"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"}}]}]
outputjson[{"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.
nixCFGVER=$(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"
nixCFGVER=$(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"
outputtextHTTP 202
outputtextHTTP 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.
nixCFGVER=$(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"
nixCFGVER=$(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"
outputtextHTTP 202
outputtextHTTP 202
Add force_reload=true to wait for the reload:
nixCFGVER=$(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"
nixCFGVER=$(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"
outputtextHTTP 204
outputtextHTTP 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.
shdig @127.0.0.1 -p 153 ns1.other.example.net A +short
shdig @127.0.0.1 -p 153 ns1.other.example.net A +short
outputtext203.0.113.9
outputtext203.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.