Enterprise modules

Global server load balancing

On this page

This page applies to:

  • HAProxy Enterprise - all versions

HAProxy Enterprise can serve as an authoritative Domain Name System (DNS) server in a limited capacity, specifically for implementing global server load balancing (GSLB). This lets you respond to DNS queries with the IP address(es) assigned to a datacenter that is the best match for the end user, such as the one that is geographically closest to them. Or, you can configure DNS to return the address of a secondary datacenter if the primary becomes inaccessible.

By providing GSLB, you can fulfill the following use cases:

  • DNS round-robin: Distributes traffic between all datacenters in multiple locations.

  • Failover: Send all traffic to a primary datacenter by returning its IP address(es) in DNS responses, and direct traffic to a secondary datacenter if the primary becomes inaccessible.

  • Geolocation-based DNS: GSLB enhances functionalities of the DNS naming system by distributing network traffic across servers located in multiple locations. It can detect users’ locations and route traffic to the nearest datacenter to lower latency.

The load balancer continuously monitors the health of your datacenter IP addresses so that it can remove them from the DNS responses if they become unavailable. It reroutes the traffic to another available datacenter by changing DNS records dynamically.

How global server load balancing works Jump to heading

First, consider how DNS typically works. DNS servers translate human-readable domain names (for example, www.example.com) to numeric IP addresses (for example, 10.10.0.5).

  1. A client’s web browser queries the DNS server to get the IP address of a website.
  2. The DNS server returns an IP addresses.
  3. The browser connects to the website through its IP address.

Global server load balancing offers a DNS server a smarter way to choose which IP address it should return. It can take into account where the client is located in the world and the health of each datacenter before selecting the IP address to return in a DNS response. This allows it to send a client to the best match.

  1. A client’s web browser queries the DNS server to get the IP address of a website.
  2. HAProxy Enterprise, acting as the DNS server returns an IP address, but one based on the geographic IP location of the client and/or the health of the datacenter.
  3. The client gets the best possible user experience by connecting to the website through the IP address of the datacenter that is the best match for them.

HAProxy Enterprise polls the servers to make sure they remain responsive. If they stop responding, then the affected IP addresses will be removed from the list of valid responses HAProxy Enterprise will return to clients.

One caveat: GSLB uses DNS to route clients, and DNS responses are often cached. If a datacenter becomes unavailable, clients will continue to use the cached IP address returned in the original DNS response until the cached response expires. However, it remains an effective strategy overall for distributing traffic across datacenters.

Install the GSLB module Jump to heading

  1. Provision a server on which you will install the GSLB module.

  2. On the provisioned server, add package repositories for your operating system.

    In a terminal window, set a variable named key to your HAProxy Enterprise license key.

    nix
    key=<HAProxy Enterprise Key>
    nix
    key=<HAProxy Enterprise Key>

    Use the echo and tee commands to add the HAProxy Technologies extras repository location into the file /etc/apt/sources.list.d/haproxy-tech.list, as shown below.

    nix
    echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/HAPEE-key-extras.asc] https://www.haproxy.com/download/hapee/key/${key}-plus/extras/debian-$(. /etc/os-release && echo "$VERSION_CODENAME")/amd64/ $(. /etc/os-release && echo "$VERSION_CODENAME") main" | sudo tee -a /etc/apt/sources.list.d/haproxy-tech.list
    nix
    echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/HAPEE-key-extras.asc] https://www.haproxy.com/download/hapee/key/${key}-plus/extras/debian-$(. /etc/os-release && echo "$VERSION_CODENAME")/amd64/ $(. /etc/os-release && echo "$VERSION_CODENAME") main" | sudo tee -a /etc/apt/sources.list.d/haproxy-tech.list

    The packages that HAProxy Technologies provides are signed. To install them, import the public key:

    nix
    sudo apt-get update
    sudo apt-get install --yes apt-transport-https curl dirmngr gnupg-agent grep
    sudo mkdir -p /etc/apt/keyrings
    sudo curl -s -L "https://pks.haproxy.com/linux/enterprise/HAPEE-key-extras.asc" -o /etc/apt/keyrings/HAPEE-key-extras.asc
    nix
    sudo apt-get update
    sudo apt-get install --yes apt-transport-https curl dirmngr gnupg-agent grep
    sudo mkdir -p /etc/apt/keyrings
    sudo curl -s -L "https://pks.haproxy.com/linux/enterprise/HAPEE-key-extras.asc" -o /etc/apt/keyrings/HAPEE-key-extras.asc

    In a terminal window, set a variable named key to your HAProxy Enterprise license key.

    nix
    key=<HAProxy Enterprise Key>
    nix
    key=<HAProxy Enterprise Key>

    Use the echo and tee commands to add the HAProxy Technologies extras repository location into the file /etc/apt/sources.list.d/haproxy-tech.list, as shown below.

    nix
    echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/HAPEE-key-extras.asc] https://www.haproxy.com/download/hapee/key/${key}-plus/extras/ubuntu-$(. /etc/os-release && echo "$VERSION_CODENAME")/amd64/ $(. /etc/os-release && echo "$VERSION_CODENAME") main" | sudo tee -a /etc/apt/sources.list.d/haproxy-tech.list
    nix
    echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/HAPEE-key-extras.asc] https://www.haproxy.com/download/hapee/key/${key}-plus/extras/ubuntu-$(. /etc/os-release && echo "$VERSION_CODENAME")/amd64/ $(. /etc/os-release && echo "$VERSION_CODENAME") main" | sudo tee -a /etc/apt/sources.list.d/haproxy-tech.list

    The packages that HAProxy Technologies provides are signed. To install them, import the public key:

    nix
    sudo apt-get update
    sudo apt-get install --yes apt-transport-https curl dirmngr gnupg-agent grep
    sudo mkdir -p /etc/apt/keyrings
    sudo curl -s -L "https://pks.haproxy.com/linux/enterprise/HAPEE-key-extras.asc" -o /etc/apt/keyrings/HAPEE-key-extras.asc
    nix
    sudo apt-get update
    sudo apt-get install --yes apt-transport-https curl dirmngr gnupg-agent grep
    sudo mkdir -p /etc/apt/keyrings
    sudo curl -s -L "https://pks.haproxy.com/linux/enterprise/HAPEE-key-extras.asc" -o /etc/apt/keyrings/HAPEE-key-extras.asc

    Create a new file /etc/yum.repos.d/haproxy-tech.repo if it doesn’t exist, and add the contents below. Replace <HAProxy Enterprise Key> with the HAProxy Enterprise license key you were given when you registered. Also replace rhel-8 with your RHEL version number.

    haproxy-tech.repo
    ini
    [hapee-plus-extras]
    name=hapee-plus-extras
    enabled=1
    baseurl=https://www.haproxy.com/download/hapee/key/<HAProxy Enterprise Key>-plus/extras/rhel-8/$basearch/bin/
    gpgcheck=1
    haproxy-tech.repo
    ini
    [hapee-plus-extras]
    name=hapee-plus-extras
    enabled=1
    baseurl=https://www.haproxy.com/download/hapee/key/<HAProxy Enterprise Key>-plus/extras/rhel-8/$basearch/bin/
    gpgcheck=1

    The packages that HAProxy Technologies provides are signed. To install them, import the public key:

    nix
    rpm --import https://pks.haproxy.com/linux/enterprise/HAPEE-key-extras.asc
    nix
    rpm --import https://pks.haproxy.com/linux/enterprise/HAPEE-key-extras.asc

  3. Install the GSLB package according to your platform:

    nix
    sudo apt-get install hapee-extras-gslb
    nix
    sudo apt-get install hapee-extras-gslb
    nix
    sudo yum install hapee-extras-gslb
    nix
    sudo yum install hapee-extras-gslb
    nix
    sudo zypper install hapee-extras-gslb
    nix
    sudo zypper install hapee-extras-gslb
    nix
    sudo pkg install hapee-extras-gslb
    nix
    sudo pkg install hapee-extras-gslb

  4. Optional: By default, the GSLB service listens for DNS queries at the addresses 0.0.0.0:53 and 127.0.0.1:153. To change this, edit the GSLB service file:

    • On Debian/Ubuntu, /etc/default/hapee-extras-gslb
    • On Alma/Oracle/Red Hat/Rocky, /etc/sysconfig/hapee-extras-gslb

    Change the GSLB_LISTEN directive to set the IP addresses and ports at which the GSLB service should listen for DNS queries.

    hapee-extras-gslb
    text
    # Options for hapee-extras-gslb.
    GSLB_LISTEN="0.0.0.0:53 127.0.0.1:153"
    GSLB_CONFIGFILE="/etc/hapee-extras/hapee-gslb.conf"
    GSLB_CONFIGPATH="/var/run/hapee-extras/gslb"
    GSLB_RUNPATH="/var/lib/gslb"
    GSLB_HTTPS_PROXY="127.0.0.1:8080"
    ## - multiple sources extension examples
    #GSLB_ZONES_INIT="200"
    #GSLB_ZONES_DBG="1"
    #GSLB_ZONES_IDIR="/etc/hapee-extras/GSLB"
    #GSLB_ZONES_ODIR="/tmp/hapee-extras"
    #GSLB_ZONES_FILE="gslb-zones.conf"
    #GSLB_ZONES_LIST=""
    hapee-extras-gslb
    text
    # Options for hapee-extras-gslb.
    GSLB_LISTEN="0.0.0.0:53 127.0.0.1:153"
    GSLB_CONFIGFILE="/etc/hapee-extras/hapee-gslb.conf"
    GSLB_CONFIGPATH="/var/run/hapee-extras/gslb"
    GSLB_RUNPATH="/var/lib/gslb"
    GSLB_HTTPS_PROXY="127.0.0.1:8080"
    ## - multiple sources extension examples
    #GSLB_ZONES_INIT="200"
    #GSLB_ZONES_DBG="1"
    #GSLB_ZONES_IDIR="/etc/hapee-extras/GSLB"
    #GSLB_ZONES_ODIR="/tmp/hapee-extras"
    #GSLB_ZONES_FILE="gslb-zones.conf"
    #GSLB_ZONES_LIST=""

  5. Create and edit your GSLB configuration file with the file name and location: /etc/hapee-extras/hapee-gslb.conf. You can copy over the example configuration template to get started, or use it as a reference with:

    nix
    sudo cp /etc/hapee-extras/hapee-gslb-example.conf /etc/hapee-extras/hapee-gslb.conf
    nix
    sudo cp /etc/hapee-extras/hapee-gslb-example.conf /etc/hapee-extras/hapee-gslb.conf

  6. Save your configuration, then enable and start the GSLB service.

    nix
    sudo systemctl enable hapee-extras-gslb
    sudo systemctl start hapee-extras-gslb
    nix
    sudo systemctl enable hapee-extras-gslb
    sudo systemctl start hapee-extras-gslb

Scenarios Jump to heading

The following sections describe how to configure the GSLB module for several scenarios.

DNS round-robin load-balancing Jump to heading

You can make the GSLB service return several IP addresses from healthy datacenters in a round-robin weighted fashion.

  1. Edit /etc/hapee-extras/hapee-gslb.conf.

    • Replace the domain example.com with your domain name and record entries.
    • Add a new list record to the zone section. A record of type list is a dynamic record followed by list of space-separated answer-list names.
    • Create answer-list sections that set IP addresses to return in a round-robin rotation. Optionally, add different weights to the answer-record lines.
    hapee-gslb.conf
    text
    zone example.com
      ttl 10
      # ORIGIN records
      record @ SOA ns1.example.com hostmaster.example.com 1 86400 3600 3600 3600 60
      record @ NS  ns1.example.com
      record @ ttl 3600 MX 100 mail1.example.com
      
      # Static records
      record ns1   ttl 20 A 10.0.0.1
      record mail1 ttl 20 A 10.0.0.2
      
      # Dynamic records
      record www   ttl 20 list dc1
    answer-list dc1
      method single-rr
      option httpchk
      http-check connect
      http-check send uri /health.html hdr host www.example.com
      answer-record srv1 20.0.0.1 weight 10
      answer-record srv2 20.0.0.2 weight 20
    hapee-gslb.conf
    text
    zone example.com
      ttl 10
      # ORIGIN records
      record @ SOA ns1.example.com hostmaster.example.com 1 86400 3600 3600 3600 60
      record @ NS  ns1.example.com
      record @ ttl 3600 MX 100 mail1.example.com
      
      # Static records
      record ns1   ttl 20 A 10.0.0.1
      record mail1 ttl 20 A 10.0.0.2
      
      # Dynamic records
      record www   ttl 20 list dc1
    answer-list dc1
      method single-rr
      option httpchk
      http-check connect
      http-check send uri /health.html hdr host www.example.com
      answer-record srv1 20.0.0.1 weight 10
      answer-record srv2 20.0.0.2 weight 20

    The answer-list section syntax is as follows:

    Directive Description
    method Set the single-rr parameter.
    option Specify httpchk to monitor the health of servers.
    http-check Set any relevant health check parameters.
    answer-record Enter any number of answer-record directives along with the corresponding IP addresses. Weights determine how often a particular IP address will be returned, with higher weights being chosen more often. By specifying method single-rr, HAProxy Enterprise alternates which IP for a datacenter it sends to clients in order to distribute traffic across all servers. In that case, the odds of a server’s IP being returned is server weight / sum of all server weights.

  2. Save your configuration and restart the GSLB service:

    nix
    sudo systemctl restart hapee-extras-gslb 
    nix
    sudo systemctl restart hapee-extras-gslb

Geolocation-based load balancing Jump to heading

You can deliver content to users based on their geographic location. HAProxy Enterprise with global server load balancing enabled returns the IP address from the closest healthy datacenter or server. To use this feature, you will need to download a GeoIP database from MaxMind.

For example, you can:

  • comply with regulations governing the location of data storage.
  • reduce latency.
  • deliver content that is tailored to users’ country and native language.

To enable geolocation-based load balancing:

  1. Create your account through the MaxMind website and download the GeoIP databases.

    What is a geolocation database?

    You can store GeoIP database files, typically in a specific format like MaxMind’s GeoIP2 or GeoLite2. GeoIP data is information about the geographical location of IP addresses. This data is used in GSLB to determine the optimal routing of client requests based on their geographic location. These database files contain mappings between IP addresses and their corresponding geographical information, such as country, region, city, and latitude/longitude coordinates.

    When a client makes a request to the GSLB system, the system can analyze the client’s IP address and consult the GeoIP database to determine the client’s location. Based on this information, the GSLB system can make intelligent routing decisions to direct the client’s request to the most appropriate server or data center that can serve the request efficiently and optimize network performance.

  2. Create a directory on the load balancer to store the geolocation databases. Copy the MaxMind GeoIP files to the directory. For example, City and ISP data: /data/GeoIP2-City.mmdb, /data/GeoIP2-ISP.mmdb.

  3. Edit /etc/hapee-extras/hapee-gslb.conf.

    • Replace the domain example.com with your domain name and record entries.
    • Add a new map record to the zone section. A record of type map is a dynamic record followed by a geoip-map name.
    • Create geoip-map sections that set answer-list sections to use depending on the client’s location.
    • Create answer-list sections. Below, the answer-list for DC1 contains a list of IP addresses for the datacenter in Europe, while the DC2 answer-list contains a list of IP addresses for the datacenter in North America.
    hapee-gslb.conf
    text
    zone example.com
      ttl 84600
      record @ ttl 900  SOA   ns1 hostmaster 1 7200 30M 3D 900 
      record @          NS    ns1.example.com. 
      record ns1        A     203.0.113.1   # nameserver: Load balancer IP address
      record alias      CNAME www
      record www        map   mymap 
    geoip-map mymap
      location-base /data/geoip/GeoLite2-City.mmdb
      location EU/FR/Paris DC1 DC2
      location NA/US/Chicago DC2 DC1
      network 198.51.100.0/24 DC1 DC2
      network 203.0.113.0/24 DC2 DC1
    answer-list DC1
      up_threshold 0.5
      method single-rr
      option tcpchk fall 10 rise 10
      tcp-check connect port 80
      answer-record srv1 198.51.100.1 weight 20
      answer-record srv2 198.51.100.2 weight 20
      answer-record srv3 198.51.100.3 weight 10
      answer-record srv4 2001:db8::4001 weight 20
      answer-record srv5 2001:db8::4002 weight 20
      answer-record srv6 2001:db8::4003 weight 10
                 
    answer-list DC2
      up_threshold 0.5
      method single-rr
      option httpchk
      http-check connect
      http-check send uri /health.html hdr host www.example.com
      http-check expect status 200,301,302
      answer-record srv1 203.0.113.10  weight 20
      answer-record srv2 203.0.113.11  weight 20
      answer-record srv3 203.0.113.12  weight 10
    hapee-gslb.conf
    text
    zone example.com
      ttl 84600
      record @ ttl 900  SOA   ns1 hostmaster 1 7200 30M 3D 900 
      record @          NS    ns1.example.com. 
      record ns1        A     203.0.113.1   # nameserver: Load balancer IP address
      record alias      CNAME www
      record www        map   mymap 
    geoip-map mymap
      location-base /data/geoip/GeoLite2-City.mmdb
      location EU/FR/Paris DC1 DC2
      location NA/US/Chicago DC2 DC1
      network 198.51.100.0/24 DC1 DC2
      network 203.0.113.0/24 DC2 DC1
    answer-list DC1
      up_threshold 0.5
      method single-rr
      option tcpchk fall 10 rise 10
      tcp-check connect port 80
      answer-record srv1 198.51.100.1 weight 20
      answer-record srv2 198.51.100.2 weight 20
      answer-record srv3 198.51.100.3 weight 10
      answer-record srv4 2001:db8::4001 weight 20
      answer-record srv5 2001:db8::4002 weight 20
      answer-record srv6 2001:db8::4003 weight 10
                 
    answer-list DC2
      up_threshold 0.5
      method single-rr
      option httpchk
      http-check connect
      http-check send uri /health.html hdr host www.example.com
      http-check expect status 200,301,302
      answer-record srv1 203.0.113.10  weight 20
      answer-record srv2 203.0.113.11  weight 20
      answer-record srv3 203.0.113.12  weight 10

    The geoip-map section syntax is as follows:

    Directive Description Example
    location-base Absolute path to the geolocation database. You can supply several geolocation database names separated by spaces. location-base /data/geoip/GeoLite2-City.mmdb
    location The first parameter is a hierarchical path to a geographic region in the order of the continent code, a country ISO code, then more specific regions like state and city name. Refer to the MaxMind reference guide and ISO-3166 for these codes. Note that GSLB will search deeper into the hierarchy if a match isn’t found at the current layer. For example, you could specify country and city name, but omit the state name between them. The second parameter is a space-separated list of answer-list section names (e.g. DC2). GSLB directs client requests sent from this location to the first healthy datacenter in the list. location NA/US/NY DC2
    network As an alternative to using location, which uses geolocation data to choose the datacenter, you can also specify a client IP range. Set a subnet value in CIDR notation followed by an ordered list of datacenters (separated by spaces). The second parameter is a space-separated list of answer-list section names (for example, DC2). GSLB directs client requests sent from this subnet to the first healthy datacenter in the list. network 198.51.100.0/24 DC1

    About the answer-list sections:

    • GSLB will send DNS responses based on the location of the client. It will only send either IPv4 or IPv6 addresses, depending on the type of IP addresses the client requests.
    • Weights determine how often a particular IP address will be returned, with higher weights being chosen more often. The weight values apply only to the IPv4 or IPv6 pool of IP addresses. In the example, the IPV4 pool of servers and the IPv6 pool of servers have their own total weight sums.
    • By specifying method single-rr, HAProxy Enterprise alternates which IP for a datacenter it sends to clients in order to distribute traffic across all servers. In that case, the odds of a server’s IP being returned is server weight / sum of all server weights.
    • You can set method multi-rr to return multiple IP addresses to the client. In that case, the odds of a server’s IP being returned is server weight / max weight value.
    • The up_threshold directive determines the percentage of servers that must be up. Otherwise, traffic is routed to a different datacenter altogether.

  4. Save your configuration and restart the GSLB service:

    nix
    sudo systemctl restart hapee-extras-gslb
    nix
    sudo systemctl restart hapee-extras-gslb

Datacenter failover Jump to heading

While you can use geolocation-based load balancing to route traffic to the datacenter nearest to the client, you can also use HAProxy Enterprise for basic failover and failback between datacenters without the geolocation component. If a critical resource fails and service is disrupted, traffic will be automatically redirected to healthy datacenters. This minimizes impact and avoids manual intervention.

  1. Edit /etc/hapee-extras/hapee-gslb.conf.

    • Replace the domain example.com with your domain name and record entries.
    • Add a new list record to the zone section. A record of type list is a dynamic record followed by list of space-separated answer-list names. Essentially, you are specifying datacenters in order of preference, with fallback datacenters following primary datacenters.
    • Create answer-list sections that match the names you listed on the list record in the zone section.

    Below, the list record www enumerates two answer-list sections, DC1 and DC2, where DC1 is the primary datacenter and DC2 is the fallback. You could list additional fallback datacenters too.

    hapee-gslb.conf
    text
    zone example.com
      ttl 10
      
      # ORIGIN records
      record @ SOA ns1.example.com hostmaster.example.com 1 86400 3600 3600 3600 60
      record @ NS  ns1.example.com
      record @ ttl 3600 MX 100  mail1.example.com
      
      # static records
      record ns1   ttl 10 A 10.0.0.1
      record mail1 ttl 10 A 10.0.0.2
      
      # dynamic records - DC1 is primary, DC2 is a fallback
      record www ttl 30 list DC1 DC2
    answer-list DC1
      up_threshold 1
      method multi-up
      option httpchk
      http-check connect
      http-check send uri /health.html hdr host www.example.com
      http-check expect status 200,301,302
      answer-record srv1 20.0.0.1
    answer-list DC2
      up_threshold 1
      method multi-up
      option httpchk
      http-check connect
      http-check send uri /health.html hdr host www.example.com
      answer-record srv1 30.0.0.1
    hapee-gslb.conf
    text
    zone example.com
      ttl 10
      
      # ORIGIN records
      record @ SOA ns1.example.com hostmaster.example.com 1 86400 3600 3600 3600 60
      record @ NS  ns1.example.com
      record @ ttl 3600 MX 100  mail1.example.com
      
      # static records
      record ns1   ttl 10 A 10.0.0.1
      record mail1 ttl 10 A 10.0.0.2
      
      # dynamic records - DC1 is primary, DC2 is a fallback
      record www ttl 30 list DC1 DC2
    answer-list DC1
      up_threshold 1
      method multi-up
      option httpchk
      http-check connect
      http-check send uri /health.html hdr host www.example.com
      http-check expect status 200,301,302
      answer-record srv1 20.0.0.1
    answer-list DC2
      up_threshold 1
      method multi-up
      option httpchk
      http-check connect
      http-check send uri /health.html hdr host www.example.com
      answer-record srv1 30.0.0.1

    The answer-list section syntax is as follows:

    Directive Description
    up_threshold Determines the percentage of servers that must be up. Otherwise, traffic is routed to a different datacenter altogether. A threshold of 1 means that all servers in an answer-list must be healthy for the corresponding datacenter to be regarded as active. If you specify 0.1, then 10% of the total weighted number of servers must be up.
    method Determines which IP addresses to return. As with geolocation-based load balancing, you can return a single IP in a round-robin rotation (single-rr), multiple addresses in a round-robin rotation (method multi-rr), all servers that are up (method multi-up), or all servers, even if they are down (method multi-all).
    option Specify httpchk to monitor the health of servers. If the servers are HAProxy Enterprise load balancers, you can use monitor URI as the health check endpoint.
    http-check Set any relevant health check parameters.
    answer-record Enter any number of answer-record directives, which denote IP addresses assigned to the datacenter.

  2. Save your configuration and restart the GSLB service:

    nix
    sudo systemctl restart hapee-extras-gslb
    nix
    sudo systemctl restart hapee-extras-gslb

Enable HTTPS health checks Jump to heading

This section applies to:

  • HAProxy ALOHA 17.5 and newer
  • HAProxy Enterprise 3.2r1 and newer

The GSLB module is a wrapper around the GDNSD software. GDNSD on its own doesn’t support SSL/TLS, and as such, doesn’t support health checks requiring such a connection. To enable health checks over HTTPS, the GSLB module must use the load balancer as a proxy for its health checks.

Run in this way, the GSLB module will send its HTTPS health checks to an IP address and port defined in its service environment file (hapee-extras-gslb), in a variable named GSLB_HTTPS_PROXY. The default value for this property is 127.0.0.1:8080. The load balancer will listen on this IP address and port, intercepting these requests, connecting over HTTPS to the datacenters, and responding to GSLB with the results of the checks. The GSLB module populates the forwarded header of the request to include the IP address and port of the datacenter the load balancer will connect to to perform a health check.

Tip

If port 8080 is unavailable to the load balancer and GSLB on your system, you can change this value in the environment file and restart the hapee-extras-gslb service to pick up the change. You’ll use this value later when you define the listening IP address and port in your load balancer frontend that will proxy the HTTPS health checks.

To enable health checks over HTTPS:

  1. Edit /etc/hapee-extras/hapee-gslb.conf. Define the HTTPS health check port the load balancer will use and add the ssl keyword to the http-check connect line(s):

    hapee-gslb.conf
    text
    zone example.com
      ttl 10
      
      # ORIGIN records
      record @ SOA ns1.example.com hostmaster.example.com 1 86400 3600 3600 3600 60
      record @ NS  ns1.example.com
      record @ ttl 3600 MX 100  mail1.example.com
      
      # static records
      record ns1   ttl 10 A 10.0.0.1
      record mail1 ttl 10 A 10.0.0.2
      
      # dynamic records - DC1 is primary, DC2 is a fallback
      record www ttl 30 list DC1 DC2
    answer-list DC1
      up_threshold 1
      method multi-up
      option httpchk
      http-check connect port 443 ssl
      http-check send uri /health.html hdr host www.example.com
      http-check expect status 200,301,302
      answer-record srv1 20.0.0.1
    answer-list DC2
      up_threshold 1
      method multi-up
      option httpchk
      http-check connect port 443 ssl
      http-check send uri /health.html hdr host www.example.com
      answer-record srv1 30.0.0.1
    hapee-gslb.conf
    text
    zone example.com
      ttl 10
      
      # ORIGIN records
      record @ SOA ns1.example.com hostmaster.example.com 1 86400 3600 3600 3600 60
      record @ NS  ns1.example.com
      record @ ttl 3600 MX 100  mail1.example.com
      
      # static records
      record ns1   ttl 10 A 10.0.0.1
      record mail1 ttl 10 A 10.0.0.2
      
      # dynamic records - DC1 is primary, DC2 is a fallback
      record www ttl 30 list DC1 DC2
    answer-list DC1
      up_threshold 1
      method multi-up
      option httpchk
      http-check connect port 443 ssl
      http-check send uri /health.html hdr host www.example.com
      http-check expect status 200,301,302
      answer-record srv1 20.0.0.1
    answer-list DC2
      up_threshold 1
      method multi-up
      option httpchk
      http-check connect port 443 ssl
      http-check send uri /health.html hdr host www.example.com
      answer-record srv1 30.0.0.1

    The GSLB module will add the IP address and port to the forwarded header in the health check request. The load balancer will then use the value of the forwarded header to connect to that IP address and port for the health check over HTTPS.

  2. Add a new frontend and a new backend to your load balancer configuration:

    • The frontend will bind on the address and port as GSLB_HTTPS_PROXY as set in hapee-extras-gslb. This is where the load balancer will listen for health check requests. Default: 127.0.0.1:8080.
    • The backend will:
      • Extract the destination IP and port from the forwarded header of the request. These are set in txn.port and txn.addr.
      • Use http-request set-dst to set the destination IP address to the IP address set in txn.dest. If the address is IPv6, it will remove any brackets.
      • Use http-request set-dst-port to set the destination port.
      • Determine whether to connect over IPv4 or IPv6 based on the value of the extracted forwarded IP and port.
      • Use the ssl keyword to connect to the server over HTTPS with verify required. Specify the location of your ca-file. Set the server’s IP address to 0.0.0.0:0 ([::]:0 for IPv6) to instruct the load balancer to use the IP and port set by http-request set-dst and http-request set-dst-port.
    hapee-lb.cfg
    haproxy
    frontend gslb-fe
      bind 127.0.0.1:8080
      default_backend gslb-be
    backend  gslb-be
      balance source
      http-request set-var(txn.port) req.hdr(forwarded),rfc7239_field(host),port_only
      http-request set-var(txn.addr) req.hdr(forwarded),rfc7239_field(host),host_only
      http-request set-var(txn.dest) var(txn.addr) if !{ var(txn.addr) -m sub ":" }
      http-request set-var(txn.dest) var(txn.addr),field(2,"[]",1) if  { var(txn.addr) -m sub ":" }
                 
      http-request set-dst           var(txn.dest)
      http-request set-dst-port      var(txn.port)
                
      use-server v4                  if ! { var(txn.addr) -m sub ":" }
      use-server v6                  if   { var(txn.addr) -m sub ":" }
      server v4                      0.0.0.0:0 ssl verify required ca-file my_ca.pem weight 0
      server v6                      [::]:0 ssl verify required ca-file my_ca.pem weight 0
    hapee-lb.cfg
    haproxy
    frontend gslb-fe
      bind 127.0.0.1:8080
      default_backend gslb-be
    backend  gslb-be
      balance source
      http-request set-var(txn.port) req.hdr(forwarded),rfc7239_field(host),port_only
      http-request set-var(txn.addr) req.hdr(forwarded),rfc7239_field(host),host_only
      http-request set-var(txn.dest) var(txn.addr) if !{ var(txn.addr) -m sub ":" }
      http-request set-var(txn.dest) var(txn.addr),field(2,"[]",1) if  { var(txn.addr) -m sub ":" }
                 
      http-request set-dst           var(txn.dest)
      http-request set-dst-port      var(txn.port)
                
      use-server v4                  if ! { var(txn.addr) -m sub ":" }
      use-server v6                  if   { var(txn.addr) -m sub ":" }
      server v4                      0.0.0.0:0 ssl verify required ca-file my_ca.pem weight 0
      server v6                      [::]:0 ssl verify required ca-file my_ca.pem weight 0

  3. Restart the GSLB service:

    nix
    sudo systemctl restart hapee-extras-gslb 
    nix
    sudo systemctl restart hapee-extras-gslb

  4. Restart the load balancer:

    nix
    sudo systemctl reload hapee-3.2-lb
    nix
    sudo systemctl reload hapee-3.2-lb

The GSLB logs show that the connections are UP:

log output
text
gdnsd[1836]: state of '20.0.0.1/DC1' changed from DOWN/10 to UP/10
gdnsd[1836]: state of '30.0.0.1/DC2' changed from DOWN/10 to UP/10
log output
text
gdnsd[1836]: state of '20.0.0.1/DC1' changed from DOWN/10 to UP/10
gdnsd[1836]: state of '30.0.0.1/DC2' changed from DOWN/10 to UP/10

Troubleshooting HTTPS health checks Jump to heading

If the GSLB logs show that the connections are DOWN:

text
gdnsd[1836]: state of '20.0.0.1/DC1' changed from UP/10 to DOWN/10
gdnsd[1836]: state of '30.0.0.1/DC2' changed from UP/10 to DOWN/10
text
gdnsd[1836]: state of '20.0.0.1/DC1' changed from UP/10 to DOWN/10
gdnsd[1836]: state of '30.0.0.1/DC2' changed from UP/10 to DOWN/10

The load balancer may be having trouble connecting to the servers. To investigate, you can try the following:

Check the contents of the forwarded header in the health check requests.

Temporarily add a log-format statement to your GSLB backend to log the contents of the forwarded header and the FQDN (fully qualified domain name). Ensure that these values are as you expect:

hapee-lb.cfg
haproxy
frontend gslb-fe
  bind 127.0.0.1:8080
  log-format "%ci:%cp [%t] %ft %b/%s %Tq/%Tw/%Tc/%Tr/%Tt %ST %B %CC %CS %tsc %ac/%fc/%bc/%sc/%rc %sq/%bq %hr %hs { forwarded(%[var(txn.forwarded)]) addr(%[var(txn.addr)]) dest(%[var(txn.dest)]) port(%[var(txn.port)]) host(%[var(txn.fqdn)]) }"
  default_backend gslb-be
backend  gslb-be
  balance source
  http-request set-var(txn.forwarded) req.hdr(forwarded)
  http-request set-var(txn.fqdn)      req.hdr(host)
  http-request set-var(txn.port)      req.hdr(forwarded),rfc7239_field(host),port_only
  http-request set-var(txn.addr)      req.hdr(forwarded),rfc7239_field(host),host_only
  http-request set-var(txn.dest)      var(txn.addr) if !{ var(txn.addr) -m sub ":" }
  http-request set-var(txn.dest)      var(txn.addr),field(2,"[]",1) if  { var(txn.addr) -m sub ":" }
            
  http-request set-dst                var(txn.dest)
  http-request set-dst-port           var(txn.port)
            
  use-server v4                       if ! { var(txn.addr) -m sub ":" }
  use-server v6                       if   { var(txn.addr) -m sub ":" }
  server v4                           0.0.0.0:0 ssl verify required ca-file my_ca.pem weight 0
  server v6                           [::]:0 ssl verify required ca-file my_ca.pem weight 0
hapee-lb.cfg
haproxy
frontend gslb-fe
  bind 127.0.0.1:8080
  log-format "%ci:%cp [%t] %ft %b/%s %Tq/%Tw/%Tc/%Tr/%Tt %ST %B %CC %CS %tsc %ac/%fc/%bc/%sc/%rc %sq/%bq %hr %hs { forwarded(%[var(txn.forwarded)]) addr(%[var(txn.addr)]) dest(%[var(txn.dest)]) port(%[var(txn.port)]) host(%[var(txn.fqdn)]) }"
  default_backend gslb-be
backend  gslb-be
  balance source
  http-request set-var(txn.forwarded) req.hdr(forwarded)
  http-request set-var(txn.fqdn)      req.hdr(host)
  http-request set-var(txn.port)      req.hdr(forwarded),rfc7239_field(host),port_only
  http-request set-var(txn.addr)      req.hdr(forwarded),rfc7239_field(host),host_only
  http-request set-var(txn.dest)      var(txn.addr) if !{ var(txn.addr) -m sub ":" }
  http-request set-var(txn.dest)      var(txn.addr),field(2,"[]",1) if  { var(txn.addr) -m sub ":" }
            
  http-request set-dst                var(txn.dest)
  http-request set-dst-port           var(txn.port)
            
  use-server v4                       if ! { var(txn.addr) -m sub ":" }
  use-server v6                       if   { var(txn.addr) -m sub ":" }
  server v4                           0.0.0.0:0 ssl verify required ca-file my_ca.pem weight 0
  server v6                           [::]:0 ssl verify required ca-file my_ca.pem weight 0

This will produce a log message similar to the following:

text
Oct  2 14:59:21 hapee-01 hapee-lb[1854]: 127.0.0.1:44500 [02/Oct/2025:14:59:21.458] gslb-fe gslb-be/v4 0/0/1/1/+2 200 +165 - - ---- 1/1/1/1/0 0/0 { forwarded(host="20.0.0.1:443") addr(20.0.0.1) dest(20.0.0.1) port(443) host(www.example.com) }
text
Oct  2 14:59:21 hapee-01 hapee-lb[1854]: 127.0.0.1:44500 [02/Oct/2025:14:59:21.458] gslb-fe gslb-be/v4 0/0/1/1/+2 200 +165 - - ---- 1/1/1/1/0 0/0 { forwarded(host="20.0.0.1:443") addr(20.0.0.1) dest(20.0.0.1) port(443) host(www.example.com) }

Here is an example that resulted in a 503 Service Unavailable:

text
Oct  3 17:01:34 ip-172-31-16-187 hapee-lb[1934]: 127.0.0.1:35466 [03/Oct/2025:17:01:21.246] gslb-fe gslb-be/v4 0/0/-1/-1/13065 503 217 - - SC-- 2/2/1/0/3 0/0 { forwarded(host="172.31.28.41:443") addr(172.31.28.41) dest(172.31.28.41) port(443) host(www.example.com) }
text
Oct  3 17:01:34 ip-172-31-16-187 hapee-lb[1934]: 127.0.0.1:35466 [03/Oct/2025:17:01:21.246] gslb-fe gslb-be/v4 0/0/-1/-1/13065 503 217 - - SC-- 2/2/1/0/3 0/0 { forwarded(host="172.31.28.41:443") addr(172.31.28.41) dest(172.31.28.41) port(443) host(www.example.com) }

Run the load balancer in debug and foreground mode

You can get verbose output from the load balancer about the requests and responses it sends and receives by running the load balancer temporarily in debug and foreground mode. Note that this is for debugging / troubleshooting only, so don’t do this in a production environment.

  1. Stop the load balancer service:

    nix
    sudo systemctl stop hapee-3.2-lb
    nix
    sudo systemctl stop hapee-3.2-lb

  2. Run the load balancer in debug and foreground mode using the -d and -f options.

    nix
    /opt/hapee-3.2/sbin/hapee-lb -d -f /etc/hapee-3.2/hapee-lb.cfg
    nix
    /opt/hapee-3.2/sbin/hapee-lb -d -f /etc/hapee-3.2/hapee-lb.cfg

The load balancer will begin producing output for the health check requests it receives from GSLB. This may provide you some insight into where the health check is failing.

An example successful health check:

text
00000004:gslb-fe.accept(0004)=000e from [127.0.0.1:60162] ALPN=<none>
00000004:gslb-fe.clireq[000e:ffffffff]: GET /health HTTP/1.1
00000004:gslb-fe.clihdr[000e:ffffffff]: host: 172.31.28.41
00000004:gslb-fe.clihdr[000e:ffffffff]: forwarded: host="172.31.28.41:443"
00000004:gslb-fe.clihdr[000e:ffffffff]: user-agent: gdnsd-monitor
00000004:gslb-be.srvrep[000e:0011]: HTTP/1.0 200 OK
00000004:gslb-be.srvhdr[000e:0011]: server: Werkzeug/3.1.3 Python/3.9.21
00000004:gslb-be.srvhdr[000e:0011]: date: Thu, 02 Oct 2025 02:42:41 GMT
00000004:gslb-be.srvhdr[000e:0011]: content-type: text/html; charset=utf-8
00000004:gslb-be.srvhdr[000e:0011]: content-length: 12
text
00000004:gslb-fe.accept(0004)=000e from [127.0.0.1:60162] ALPN=<none>
00000004:gslb-fe.clireq[000e:ffffffff]: GET /health HTTP/1.1
00000004:gslb-fe.clihdr[000e:ffffffff]: host: 172.31.28.41
00000004:gslb-fe.clihdr[000e:ffffffff]: forwarded: host="172.31.28.41:443"
00000004:gslb-fe.clihdr[000e:ffffffff]: user-agent: gdnsd-monitor
00000004:gslb-be.srvrep[000e:0011]: HTTP/1.0 200 OK
00000004:gslb-be.srvhdr[000e:0011]: server: Werkzeug/3.1.3 Python/3.9.21
00000004:gslb-be.srvhdr[000e:0011]: date: Thu, 02 Oct 2025 02:42:41 GMT
00000004:gslb-be.srvhdr[000e:0011]: content-type: text/html; charset=utf-8
00000004:gslb-be.srvhdr[000e:0011]: content-length: 12

There is no response from the server in the following example’s unsuccessful health check:

text
00000006:gslb-fe.accept(0004)=000f from [127.0.0.1:56556] ALPN=<none>
00000006:gslb-fe.clireq[000f:ffffffff]: GET /health HTTP/1.1
00000006:gslb-fe.clihdr[000f:ffffffff]: host: www.example.com
00000006:gslb-fe.clihdr[000f:ffffffff]: forwarded: host="172.31.28.41:443"
00000006:gslb-fe.clihdr[000f:ffffffff]: user-agent: gdnsd-monitor
text
00000006:gslb-fe.accept(0004)=000f from [127.0.0.1:56556] ALPN=<none>
00000006:gslb-fe.clireq[000f:ffffffff]: GET /health HTTP/1.1
00000006:gslb-fe.clihdr[000f:ffffffff]: host: www.example.com
00000006:gslb-fe.clihdr[000f:ffffffff]: forwarded: host="172.31.28.41:443"
00000006:gslb-fe.clihdr[000f:ffffffff]: user-agent: gdnsd-monitor

Enable GSLB template file aggregation Jump to heading

This section applies to:

  • HAProxy ALOHA 17.5 and newer
  • HAProxy Enterprise 3.2r1 and newer

Are you managing more than a thousand zone, answer-list, and geoip-map sections and finding it difficult to manage them all in a single /etc/hapee-extras/hapee-gslb.conf GSLB configuration file? Consider enabling GSLB template file aggregation to manage smaller, separate GSLB template files to make configuring the GSLB module easier.

The GSLB wrapper (gslb-wrapper.sh) has two versions that you can set with the GSLB_ZONES_INIT option in the GSLB service file (hapee-extras-gslb):

  • With the default version 1.0, which is equivalent to setting GSLB_ZONES_INIT="100", the GSLB wrapper will use the settings only in the /etc/hapee-extras/hapee-gslb.conf GSLB configuration file.
  • With version 2.0, which is equivalent to setting GSLB_ZONES_INIT="200", the GSLB wrapper will use other specified GSLB template files and directories in addition to the GSLB configuration file. This wrapper is backwards compatible with version 1.0, because it will merge all of the specified files into one GSLB configuration file for the GSLB service to use.

To enable the aggregation of GSLB template files:

  1. Edit the GSLB service file. Uncomment the following GSLB_ZONES* options:

    hapee-extras-gslb
    text
    ...
    ## - multiple sources extension examples
    GSLB_ZONES_INIT="200"
    GSLB_ZONES_DBG="1"
    GSLB_ZONES_IDIR="/etc/hapee-extras/GSLB"
    GSLB_ZONES_ODIR="/tmp/hapee-extras"
    GSLB_ZONES_FILE="gslb-zones.conf"
    GSLB_ZONES_LIST=""
    hapee-extras-gslb
    text
    ...
    ## - multiple sources extension examples
    GSLB_ZONES_INIT="200"
    GSLB_ZONES_DBG="1"
    GSLB_ZONES_IDIR="/etc/hapee-extras/GSLB"
    GSLB_ZONES_ODIR="/tmp/hapee-extras"
    GSLB_ZONES_FILE="gslb-zones.conf"
    GSLB_ZONES_LIST=""

    An explanation of each option and their default values:

    Option Description
    GSLB_ZONES_INIT Sets what GSLB wrapper version to use. Must be equal to or greater than 200. Default: 200, meaning GSLB wrapper version 2.0 will be used.
    GSLB_ZONES_DBG Specifies what kind of verbosity to track during aggregation. Set 1 for tracking only errors and 2 for as much verbosity as possible. Default: 1.
    GSLB_ZONES_IDIR Sets the input directory for the GSLB wrapper to use. Default: /etc/hapee-extras/GSLB.
    GSLB_ZONES_ODIR Sets the output directory to save the aggregation result. Default: /tmp/hapee-extras.
    GSLB_ZONES_FILE Sets the name of the configuration file for the saved aggregation result. Default: gslb-zones.conf.
    GSLB_ZONES_LIST Sets what GSLB template files and directories to merge together in a space-separated list. Default: Empty.

  2. Edit the GSLB_ZONES* options and organize GSLB template files and directories to fit your use case.

    There are a couple caveats to keep in mind: the wrapper doesn’t follow symbolic links nor enter unspecified subdirectories, so utilize GSLB_ZONES_LIST accordingly. Create and configure GSLB template files like you would the GSLB configuration file, but with a different, unique file name each time.

    Expand an example

    Consider the following file and directory structure:

    nix
    /etc/hapee-extras/hapee-gslb.conf
    /etc/hapee-extras/GSLB/zones-enabled.conf
    /etc/hapee-extras/GSLB/APAC/BACKUP/past_template.conf
    /etc/hapee-extras/GSLB/APAC/zone-x-0000.conf
    /etc/hapee-extras/GSLB/APAC/zone-x-0001.conf
    /etc/hapee-extras/GSLB/APAC/zone-x-0002.conf
    /etc/hapee-extras/GSLB/EMEA/BACKUP/past_template.conf
    /etc/hapee-extras/GSLB/EMEA/zone-y-0000.conf
    /etc/hapee-extras/GSLB/EMEA/zone-y-0001.conf
    /etc/hapee-extras/GSLB/EMEA/zone-y-0002.conf
    /etc/hapee-extras/GSLB/LATAM/BACKUP/past_template.conf
    /etc/hapee-extras/GSLB/LATAM/zone-z-0000.conf
    /etc/hapee-extras/GSLB/LATAM/zone-z-0001.conf
    /etc/hapee-extras/GSLB/LATAM/zone-z-0002.conf
    nix
    /etc/hapee-extras/hapee-gslb.conf
    /etc/hapee-extras/GSLB/zones-enabled.conf
    /etc/hapee-extras/GSLB/APAC/BACKUP/past_template.conf
    /etc/hapee-extras/GSLB/APAC/zone-x-0000.conf
    /etc/hapee-extras/GSLB/APAC/zone-x-0001.conf
    /etc/hapee-extras/GSLB/APAC/zone-x-0002.conf
    /etc/hapee-extras/GSLB/EMEA/BACKUP/past_template.conf
    /etc/hapee-extras/GSLB/EMEA/zone-y-0000.conf
    /etc/hapee-extras/GSLB/EMEA/zone-y-0001.conf
    /etc/hapee-extras/GSLB/EMEA/zone-y-0002.conf
    /etc/hapee-extras/GSLB/LATAM/BACKUP/past_template.conf
    /etc/hapee-extras/GSLB/LATAM/zone-z-0000.conf
    /etc/hapee-extras/GSLB/LATAM/zone-z-0001.conf
    /etc/hapee-extras/GSLB/LATAM/zone-z-0002.conf

    To merge all these GSLB template files, ignoring the BACKUP directories, the GSLB service file is saved with:

    hapee-extras-gslb
    text
    ...
    GSLB_CONFIGFILE="/etc/hapee-extras/hapee-gslb.conf"
    ...
    GSLB_ZONES_INIT="200"
    GSLB_ZONES_DBG="2"
    GSLB_ZONES_IDIR="/etc/hapee-extras/GSLB"
    GSLB_ZONES_ODIR="/tmp/hapee-extras"
    GSLB_ZONES_FILE="gslb-zones.conf"
    GSLB_ZONES_LIST="APAC EMEA LATAM"
    hapee-extras-gslb
    text
    ...
    GSLB_CONFIGFILE="/etc/hapee-extras/hapee-gslb.conf"
    ...
    GSLB_ZONES_INIT="200"
    GSLB_ZONES_DBG="2"
    GSLB_ZONES_IDIR="/etc/hapee-extras/GSLB"
    GSLB_ZONES_ODIR="/tmp/hapee-extras"
    GSLB_ZONES_FILE="gslb-zones.conf"
    GSLB_ZONES_LIST="APAC EMEA LATAM"

    The GSLB template file aggregation will merge template files listed in GSLB_CONFIGFILE, GSLB_ZONES_IDIR, and GSLB_ZONES_LIST into one configuration file that the GSLB service will use at /tmp/hapee-extras/gslb-zones.conf.

    log output
    nix
    ... 
    ... GSLB_CONFIGFILE = /etc/hapee-extras/hapee-gslb.conf
    ... GSLB_ZONES_DBG  = 2
    ... GSLB_ZONES_IDIR = /etc/hapee-extras/GSLB
    ... GSLB_ZONES_ODIR = /tmp/hapee-extras
    ... GSLB_ZONES_FILE = gslb-zones.conf
    ... GSLB_ZONES_LIST = APAC EMEA LATAM
    ...       merging    file  : /etc/hapee-extras/GSLB/zones-enabled.conf
    ...       merging  folder  : /etc/hapee-extras/GSLB/APAC
    ...                   +--->  /etc/hapee-extras/GSLB/APAC/zone-x-0000.conf
    ...                   +--->  /etc/hapee-extras/GSLB/APAC/zone-x-0001.conf
    ...                   +--->  /etc/hapee-extras/GSLB/APAC/zone-x-0002.conf
    ...       merging  folder  : /etc/hapee-extras/GSLB/EMEA
    ...                   +--->  /etc/hapee-extras/GSLB/EMEA/zone-y-0000.conf
    ...                   +--->  /etc/hapee-extras/GSLB/EMEA/zone-y-0001.conf
    ...                   +--->  /etc/hapee-extras/GSLB/EMEA/zone-y-0002.conf
    ...       merging  folder  : /etc/hapee-extras/GSLB/LATAM
    ...                   +--->  /etc/hapee-extras/GSLB/LATAM/zone-z-0000.conf
    ...                   +--->  /etc/hapee-extras/GSLB/LATAM/zone-z-0001.conf
    ...                   +--->  /etc/hapee-extras/GSLB/LATAM/zone-z-0002.conf
    ... GSLB_CONFIGFILE = /tmp/hapee-extras/gslb-zones.conf
    ...
    log output
    nix
    ... 
    ... GSLB_CONFIGFILE = /etc/hapee-extras/hapee-gslb.conf
    ... GSLB_ZONES_DBG  = 2
    ... GSLB_ZONES_IDIR = /etc/hapee-extras/GSLB
    ... GSLB_ZONES_ODIR = /tmp/hapee-extras
    ... GSLB_ZONES_FILE = gslb-zones.conf
    ... GSLB_ZONES_LIST = APAC EMEA LATAM
    ...       merging    file  : /etc/hapee-extras/GSLB/zones-enabled.conf
    ...       merging  folder  : /etc/hapee-extras/GSLB/APAC
    ...                   +--->  /etc/hapee-extras/GSLB/APAC/zone-x-0000.conf
    ...                   +--->  /etc/hapee-extras/GSLB/APAC/zone-x-0001.conf
    ...                   +--->  /etc/hapee-extras/GSLB/APAC/zone-x-0002.conf
    ...       merging  folder  : /etc/hapee-extras/GSLB/EMEA
    ...                   +--->  /etc/hapee-extras/GSLB/EMEA/zone-y-0000.conf
    ...                   +--->  /etc/hapee-extras/GSLB/EMEA/zone-y-0001.conf
    ...                   +--->  /etc/hapee-extras/GSLB/EMEA/zone-y-0002.conf
    ...       merging  folder  : /etc/hapee-extras/GSLB/LATAM
    ...                   +--->  /etc/hapee-extras/GSLB/LATAM/zone-z-0000.conf
    ...                   +--->  /etc/hapee-extras/GSLB/LATAM/zone-z-0001.conf
    ...                   +--->  /etc/hapee-extras/GSLB/LATAM/zone-z-0002.conf
    ... GSLB_CONFIGFILE = /tmp/hapee-extras/gslb-zones.conf
    ...

  3. Once all the GSLB configuration file and template files are saved, restart the GSLB service:

    nix
    sudo systemctl restart hapee-extras-gslb
    nix
    sudo systemctl restart hapee-extras-gslb

Troubleshooting GSLB template file aggregations Jump to heading

If you see an Unreachable reference message logged, then you may have tried to aggregate a relative reference instead of an explicit reference. For example:

nix
sudo systemctl restart hapee-extras-gslb.service
journalctl -u hapee-extras-gslb.service -t "gslb-wrapper.sh"
nix
sudo systemctl restart hapee-extras-gslb.service
journalctl -u hapee-extras-gslb.service -t "gslb-wrapper.sh"
output
nix
... GSLB_CONFIGFILE = /etc/hapee-extras/hapee-gslb.conf
... GSLB_ZONES_DBG  = 2
... GSLB_ZONES_IDIR = /etc/hapee-extras/GSLB
... GSLB_ZONES_ODIR = /tmp/hapee-extras
... GSLB_ZONES_FILE = gslb-zones.conf
... GSLB_ZONES_LIST =  LATAM EMEA/zone-y-000 /etc/hapee-extras/GSLB/APAC/zone-x-0002.conf
...       merging  folder  : /etc/hapee-extras/GSLB/LATAM
...                   +--->  /etc/hapee-extras/GSLB/LATAM/zone-z-0000.conf
...                   +--->  /etc/hapee-extras/GSLB/LATAM/zone-z-0001.conf
...                   +--->  /etc/hapee-extras/GSLB/LATAM/zone-z-0002.conf
...  Unreachable reference : /etc/hapee-extras/GSLB/EMEA/zone-y-000
...       merging    file  : /etc/hapee-extras/GSLB/APAC/zone-x-0002.conf
... GSLB_CONFIGFILE = /tmp/hapee-extras/gslb-zones.conf
output
nix
... GSLB_CONFIGFILE = /etc/hapee-extras/hapee-gslb.conf
... GSLB_ZONES_DBG  = 2
... GSLB_ZONES_IDIR = /etc/hapee-extras/GSLB
... GSLB_ZONES_ODIR = /tmp/hapee-extras
... GSLB_ZONES_FILE = gslb-zones.conf
... GSLB_ZONES_LIST =  LATAM EMEA/zone-y-000 /etc/hapee-extras/GSLB/APAC/zone-x-0002.conf
...       merging  folder  : /etc/hapee-extras/GSLB/LATAM
...                   +--->  /etc/hapee-extras/GSLB/LATAM/zone-z-0000.conf
...                   +--->  /etc/hapee-extras/GSLB/LATAM/zone-z-0001.conf
...                   +--->  /etc/hapee-extras/GSLB/LATAM/zone-z-0002.conf
...  Unreachable reference : /etc/hapee-extras/GSLB/EMEA/zone-y-000
...       merging    file  : /etc/hapee-extras/GSLB/APAC/zone-x-0002.conf
... GSLB_CONFIGFILE = /tmp/hapee-extras/gslb-zones.conf

Use explicit references (such as EMEA/zone-y-0000.conf, EMEA/zone-y-0001.conf, and EMEA/zone-y-0002.conf) in GSLB_ZONES_LIST instead of relative references (in the example above, EMEA/zone-y-000 is missing the last digit according to the GSLB wrapper).

Testing Jump to heading

You can use the dig command to test implementation. For example, if your domain is example.com you can use dig www.example.com @127.0.0.1 -p 153 to test.

nix
; <<>> DiG 9.10.6 <<>> A @127.0.0.1 -p 153 example.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 4343
;; flags: qr aa rd ra ad; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; QUESTION SECTION:
;example.com.                    IN      A
;; ANSWER SECTION:
example.com.             139   IN      A       20.0.0.1
;; Query time: 0 msec
;; SERVER: 127.0.0.1#153(127.0.0.1)
;; WHEN: Tue Jul 03 23:27:15 UTC 2023
;; MSG SIZE  rcvd: 74
nix
; <<>> DiG 9.10.6 <<>> A @127.0.0.1 -p 153 example.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 4343
;; flags: qr aa rd ra ad; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; QUESTION SECTION:
;example.com.                    IN      A
;; ANSWER SECTION:
example.com.             139   IN      A       20.0.0.1
;; Query time: 0 msec
;; SERVER: 127.0.0.1#153(127.0.0.1)
;; WHEN: Tue Jul 03 23:27:15 UTC 2023
;; MSG SIZE  rcvd: 74

Logs and status Jump to heading

View logs related to GSLB:

nix
sudo journalctl -u hapee-extras-gslb -b -0 -f
nix
sudo journalctl -u hapee-extras-gslb -b -0 -f
output
text
-- Logs begin at Mon 2023-06-26 12:34:56 UTC, end at Tue 2023-06-27 08:30:00 UTC. --
  Jun 27 08:29:30 hostname haproxy[12345]: Proxy backend_1 started.
  Jun 27 08:29:35 hostname haproxy[12345]: Server backend_1/srv1 is UP.
  Jun 27 08:29:35 hostname haproxy[12345]: Server backend_1/srv2 is UP.
  Jun 27 08:29:45 hostname haproxy[12345]: Proxy backend_2 started.
  Jun 27 08:29:50 hostname haproxy[12345]: Server backend_2/srv1 is UP.
  Jun 27 08:29:50 hostname haproxy[12345]: Server backend_2/srv2 is UP.
output
text
-- Logs begin at Mon 2023-06-26 12:34:56 UTC, end at Tue 2023-06-27 08:30:00 UTC. --
  Jun 27 08:29:30 hostname haproxy[12345]: Proxy backend_1 started.
  Jun 27 08:29:35 hostname haproxy[12345]: Server backend_1/srv1 is UP.
  Jun 27 08:29:35 hostname haproxy[12345]: Server backend_1/srv2 is UP.
  Jun 27 08:29:45 hostname haproxy[12345]: Proxy backend_2 started.
  Jun 27 08:29:50 hostname haproxy[12345]: Server backend_2/srv1 is UP.
  Jun 27 08:29:50 hostname haproxy[12345]: Server backend_2/srv2 is UP.

To verify if the service is active:

nix
sudo systemctl status hapee-extras-gslb
nix
sudo systemctl status hapee-extras-gslb
output
text
● hapee-extras-gslb.service - HAPEE GSLB
    Loaded: loaded (/lib/systemd/system/hapee-extras-gslb.service; enabled; vendor preset: enabled)
    Active: active (running) since Tue 2023-06-13 01:59:44 UTC; 1 day 15h ago
  Main PID: 1234 (hapee-extras-gs)
      Tasks: 1 (limit: 4915)
    Memory: 10.0M
    CGroup: /system.slice/hapee-extras-gslb.service
            └─1234 /usr/sbin/hapee-extras-gslb --config /etc/hapee-extras/gslb.cfg
output
text
● hapee-extras-gslb.service - HAPEE GSLB
    Loaded: loaded (/lib/systemd/system/hapee-extras-gslb.service; enabled; vendor preset: enabled)
    Active: active (running) since Tue 2023-06-13 01:59:44 UTC; 1 day 15h ago
  Main PID: 1234 (hapee-extras-gs)
      Tasks: 1 (limit: 4915)
    Memory: 10.0M
    CGroup: /system.slice/hapee-extras-gslb.service
            └─1234 /usr/sbin/hapee-extras-gslb --config /etc/hapee-extras/gslb.cfg

Reference guide Jump to heading

This section describes the syntax of the zonefile, /etc/hapee-extras/hapee-gslb.conf.

Domain zone Jump to heading

A zone section defines a domain zone, a distinct part of the domain namespace. It contains one or more record directives.

Syntax:

text
zone <ZONE_NAME>
  ttl <TTL>
  record <DOMAIN_NAME string> ttl <seconds> <RECORD_TYPE> <FIELDS> 
text
zone <ZONE_NAME>
  ttl <TTL>
  record <DOMAIN_NAME string> ttl <seconds> <RECORD_TYPE> <FIELDS>

This example defines a zone for example.com.

text
zone example.com
text
zone example.com

In the following sections we describe directives found within the zone section.

Time to Live Jump to heading

The minimum TTL for records in this zone: TTL <num>. This is the default used for records unless specified otherwise in individual records.

text
zone example.com
  ttl 84600
text
zone example.com
  ttl 84600

The TTL here is 86,400 seconds, or 24 hours. DNS resolvers and clients that retrieve this DNS record will be allowed to cache it for up to 24 hours before checking for updates by querying the authoritative DNS server again.

Records Jump to heading

Records declared using the record directive provide zone responses.

Syntax:

text
record <DOMAIN_NAME string> ttl <seconds> <RECORD_TYPE> <FIELDS>
text
record <DOMAIN_NAME string> ttl <seconds> <RECORD_TYPE> <FIELDS>

Arguments include:

Argument Description
DOMAIN_NAME string Domain name as string or use @ to indicate root domain given on zone line.
ttl Time to Live in seconds for this specific record.
RECORD_TYPE Each record type can be one of the following: SOA, A, AAAA, CNAME, NS, MX, map, list.
FIELDS Fields are unique to each RECORD_TYPE.

SOA records Jump to heading

Start of Authority (SOA) records provide administrative information about the zone, like the primary name server, the email of the domain administrator, and some configuration parameters. A zone must have exactly one SOA record.

text
zone example.com
  ttl 86400
  record @ ttl 900 SOA ns1.nameserver.com. admin.example.com. 2023090501 3600 1800 604800 86400
text
zone example.com
  ttl 86400
  record @ ttl 900 SOA ns1.nameserver.com. admin.example.com. 2023090501 3600 1800 604800 86400

The SOA record’s arguments include:

Argument Description
ns1.nameserver.com The primary authoritative name server for the domain where DNS queries for this domain are initially directed.
admin.example.com The email address of the responsible party or administrator for the domain. In DNS zone files, it’s common to use an email address with a dot (.) replaced by an @ symbol to obfuscate the email and avoid spam. So, admin.example.com typically represents an email address like admin@example.com.
2023090501 The serial number, which is incremented each time the zone is updated. This helps in tracking changes to the zone.
3600 Refresh time, which indicates how often secondary name servers should check for updates to this zone. This means that any DNS queries for the alias domain will be redirected to the target domain specified in the CNAME record.
1800 Retry time, which indicates how often secondary name servers should retry if they fail to refresh the zone.
604800 Expire time, which sets a limit on how long secondary servers can continue to use the zone data if they cannot refresh it.
86400 The minimum TTL for records in this zone. This is the default used for records unless specified otherwise in individual records.

A records Jump to heading

Map a domain name to an IPv4 address.

text
record www A 203.0.113.1
text
record www A 203.0.113.1

AAAA records Jump to heading

Map a domain name to an IPv6 address.

text
example.com. AAAA 2001:0db8:85a3:0000:0000:8a2e:0370:7334
text
example.com. AAAA 2001:0db8:85a3:0000:0000:8a2e:0370:7334

CNAME records Jump to heading

Creates an alias or nickname for one domain that points to another domain’s canonical (primary) name.

text
www.example.com. CNAME example.com
text
www.example.com. CNAME example.com

MX records Jump to heading

An MX (mail exchange) record represents the mailing record for the domain. MX <Priority number> indicates the preference or priority of this mail server. Lower values represent higher priority.

Here the ttl is set to 30 seconds, and 10 is the priority value for the mail server:

text
record example.com ttl 30 MX 10 mail.example.com
text
record example.com ttl 30 MX 10 mail.example.com

NS records Jump to heading

Specifies the authoritative name servers for a domain. These servers are responsible for providing DNS information for the domain.

text
example.com. NS ns1.examplehosting.com 
example.com. NS ns2.examplehosting.com
text
example.com. NS ns1.examplehosting.com 
example.com. NS ns2.examplehosting.com

List records Jump to heading

A list of answer-list names separated by spaces associated with the domain name, for example:

text
record www2 list london paris amsterdam
text
record www2 list london paris amsterdam

Map records Jump to heading

A list of geoip-map names separated by spaces associated with the domain name, for example:

text
record www3 map mymap
text
record www3 map mymap

Answer list Jump to heading

An answer-list configuration is a set of parameters that dictate how to select and serve the best server or resource to a client based on certain conditions such as server health, load, or geographical location. It specifies the method for server selection, health check options, and other variables.

Syntax:

text
answer-list <ANSWER_LIST_NAME string>
  up_threshold <THRESHOLD number>
  method multi-up|multi-all|multi-rr|single-rr
  option httpchk|tcpchk [fall <FALL_COUNT number>] [rise <RISE_COUNT number>]
  http-check connect
  http-check send uri <URI string> hdr <HEADER_NAME string>
  http-check expect status <STATUS number>
  answer-record <NAME> [<IP>] [weight <WEIGHT number>]
text
answer-list <ANSWER_LIST_NAME string>
  up_threshold <THRESHOLD number>
  method multi-up|multi-all|multi-rr|single-rr
  option httpchk|tcpchk [fall <FALL_COUNT number>] [rise <RISE_COUNT number>]
  http-check connect
  http-check send uri <URI string> hdr <HEADER_NAME string>
  http-check expect status <STATUS number>
  answer-record <NAME> [<IP>] [weight <WEIGHT number>]
Directive Description
up_threshold Determines the percentage of servers that must be up. Otherwise, traffic is routed to a different datacenter altogether. A threshold of 1 means that all servers in an answer-list must be healthy for the corresponding datacenter to be regarded as active. If you specify 0.1, then 10% of the total weighted number of servers must be up.
method Determines which IP addresses to return. As with geolocation-based load balancing, you can: return a single IP in a round-robin rotation (single-rr), return multiple addresses in a round-robin rotation (method multi-rr), return all servers that are up (method multi-up), or return all servers, even if they are down (method multi-all)
option Specify httpchk or tcpchk to monitor the health of servers. If the servers are HAProxy Enterprise load balancers, you can use monitor URI as an HTTP health check endpoint. The health check options httpchk and tcpchk are mutually exclusive.
http-check Set any relevant health check parameters.
answer-record Enter any number of answer-record directives, which denote IP addresses assigned to the datacenter.

GeoIP map Jump to heading

A geoip-map is a configuration setting that allows you to perform geolocation-based routing using your geolocation database. This will return different IP addresses in response to client DNS queries based on their geographical location.

Syntax:

text
geoip-map <MAP_NAME string>
  location-base <PATH string>
  location <GEO string|default> <ANSWER-LISTS>
  network <SUBNET cidr> <ANSWER-LISTS>
text
geoip-map <MAP_NAME string>
  location-base <PATH string>
  location <GEO string|default> <ANSWER-LISTS>
  network <SUBNET cidr> <ANSWER-LISTS>
Directive Description Example
location-base Absolute path to the geolocation database. You can supply several geolocation database names separated by spaces. location-base /data/geoip/GeoLite2-City.mmdb
location The first parameter is a hierarchical path to a geographic region in the order of the continent code, a country ISO code, then more specific regions like state and city name. Refer to the MaxMind reference guide and ISO-3166 for these codes. Note that GSLB will search deeper into the hierarchy if a match isn’t found at the current layer. For example, you could specify country and city name, but omit the state name between them. The second parameter is a space-separated list of answer-list section names (for example, DC2). GSLB directs client requests sent from this location to the first healthy datacenter in the list. location NA/US/NY DC2
network As an alternative to using location, which uses geolocation data to choose the datacenter, you can also specify a client IP range. Set a subnet value in CIDR notation followed by an ordered list of datacenters (separated by spaces). The second parameter is a space-separated list of answer-list section names (for example, DC2). GSLB directs client requests sent from this subnet to the first healthy datacenter in the list. network 198.51.100.0/24 DC1

See also Jump to heading

  • The GSLB module is a wrapper around the GDNSD software. The syntax we use is different, but you may still find the GDNSD documentation useful.

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

Previous page Troubleshooting Next page Real-time Dashboard
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences