Enterprise modules

Global server load balancing

On this page

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, but 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 (e.g. www.example.com) to numeric IP addresses (e.g. 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. 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

  2. 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 configuration file:

    • On Debian/Ubuntu, /etc/default/hapee-extras-gslb
    • On Alma/Oracle/Redhat/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"
    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"

  3. Edit your configuration file. You can copy over the example template to get started, or use it as a reference.

    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

  4. 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

In the following sections, we describe how to configure the GSLB service 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 then 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 is not 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 (e.g. 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 then 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 then restart the GSLB service:

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

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|cname
  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|cname
  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 is not 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 (e.g. DC2). GSLB directs client requests sent from this subnet to the first healthy datacenter in the list. network 198.51.100.0/24 DC1

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

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