Load balancing

Global server load balancing

On this page

This page applies to:

  • HAProxy ALOHA 14.0 and newer

HAProxy ALOHA 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 (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 address.
  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 ALOHA, 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 ALOHA 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 ALOHA 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.

Configure the GSLB service Jump to heading

  1. In the Services tab, click gslb setup.

    GSLB setup

  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, set the listen directive to the IP address and port at which the GSLB service should listen for DNS queries.

  3. To enable the service to start automatically when the appliance boots, delete the no autostart line, click OK and then Close.

  4. To make the changes persist after a reboot, go to the Setup tab and click Save within the Configuration section.

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. In the Services tab, click [advanced mode]. Then edit the gslb configuration.

    GSLB advanced configuration

    The current configuration displays.

  2. Edit the configuration. In the example below, note the following:

    • We set the domain to example.com, but you’ll replace this with your domain name and record entries.
    • We set the directive record www ttl 20 list dc1, which is a list record in the zone section. A record of type list is a dynamic record that specifies a list of space-separated answer-list names.
    • We added an answer-list section that sets IP addresses to return in a round-robin rotation. Optionally, you can add different weights to the answer-record lines.
    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
    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 ALOHA 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.

  3. Save your configuration, close the configuration editor, then apply your changes on the gslb line in the Services tab.

    Apply GSLB changes

  4. To make your changes persistent after a reboot, click the Setup tab. Then click Save under Configuration.

Geolocation-based load balancing Jump to heading

You can deliver content to users based on their geographic location. HAProxy ALOHA 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. If your HAProxy ALOHA host is a virtual appliance instead of hardware, you need to create an additional partition large enough to contain the GeoIP databases.

    • Attach a new hard disk to the virtual machine. It should be 30 GB or larger.

    • Power on your HAProxy ALOHA Virtual Appliance.

    • Log in to your HAProxy ALOHA web UI as an administrator. The web UI runs at port 4444.

    • Select the Tools tab, then edit the file /etc/config.rc through the File Manager. Add the following directives at the end of the service system section, then click Save:

      app_auto_mount
app_auto_format
app_device_size 30000000000
      app_auto_mount
app_auto_format
app_device_size 30000000000

      where:

      • app_auto_mount automatically mounts the partition on /app.
      • app_auto_format automatically formats the /app partition, if needed.
      • app_device_size <Size in bytes> specifies the size in bytes of the /app partition. Here we set it to 30 GB.

    • Select the Setup tab, then click Save to save your modifications.

    • Restart HAProxy ALOHA.

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

  3. Use scp or Winscp to copy the databases to /app/extra on your HAProxy ALOHA server. Example:

    nix
    scp GeoIP2-City.mmdb admin@192.168.56.50:/app/extra
    nix
    scp GeoIP2-City.mmdb admin@192.168.56.50:/app/extra

  4. In the Services tab, click [advanced mode]. Then edit the gslb configuration.

    GSLB advanced configuration

    The current configuration displays.

  5. Edit the configuration:

    • 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.
    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
    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 (such as 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 (such as 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 ALOHA 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.

  6. Save your configuration, close the configuration editor, then apply your changes on the gslb line in the Services tab.

    Apply GSLB changes

  7. To make your changes persistent after a reboot, click the Setup tab. Then click Save under Configuration.

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 ALOHA 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. In the Services tab, click [advanced mode]. Then edit the gslb configuration.

    GSLB advanced configuration

    The current configuration displays.

  2. Edit the configuration:

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

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

  3. Save your configuration, close the configuration editor, then apply your changes on the gslb line in the Services tab.

    Apply GSLB changes

  4. To make your changes persistent after a reboot, click the Setup tab. Then click Save under Configuration.

Enable HTTPS health checks Jump to heading

This section applies to:

  • HAProxy ALOHA 17.5 and newer

The GSLB service 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 service 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 127.0.0.1:8080 by default. You can change this address by setting an IP address and port in the gslb service file via the https_proxy directive. 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 service file and restart the 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. From the LB Layer7 tab, add a new frontend to your load balancer configuration.

    • The frontend will bind on the address and port 127.0.0.1:8080. This is where the load balancer will listen for health check requests.
    haproxy
    frontend gslb-fe
      mode http
      bind 127.0.0.1:8080
      default_backend gslb-be
    haproxy
    frontend gslb-fe
      mode http
      bind 127.0.0.1:8080
      default_backend gslb-be

  2. Add a new backend. 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 argument on each server line to connect to the server over HTTPS.
    • The verify required argument enables verification of your certificate. You can also set verify none to disable verification.
    • The ca-file argument sets the location of the CA file to use for certificate verification.
    • 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.
    haproxy
    backend  gslb-be
      mode http
      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 /etc/haproxy/my_ca.pem weight 0
      server v6 [::]:0 ssl verify required ca-file /etc/haproxy/my_ca.pem weight 0
    haproxy
    backend  gslb-be
      mode http
      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 /etc/haproxy/my_ca.pem weight 0
      server v6 [::]:0 ssl verify required ca-file /etc/haproxy/my_ca.pem weight 0

  3. Apply your changes.

  4. In the Services tab, click gslb setup.

    GSLB setup

  5. Add the https_proxy directive.

    text
    service gslb
      ...
      https_proxy 127.0.0.1:8080
    text
    service gslb
      ...
      https_proxy 127.0.0.1:8080

  6. In the Services tab, click [advanced mode]. Then edit the gslb configuration.

    • Define the HTTPS health check port the load balancer will use and add the ssl keyword to the http-check connect line(s). In this example, we set port 443 because the remote data center servers receives HTTPS traffic on that port.
    text
    ...
    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
    text
    ...
    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.

  7. Save your configuration, close the configuration editor, then apply your changes on the gslb line in the Services tab.

    Apply GSLB changes

  8. To make your changes persistent after a reboot, click the Setup tab. Then click Save under Configuration.

    On the Logs tab, the system logs show that the connections are UP:

    text
    gdnsd[1836]: state of '20.0.0.1/DC1' initialized to UP/10
    gdnsd[1836]: state of '30.0.0.1/DC2' initialized to UP/10
    text
    gdnsd[1836]: state of '20.0.0.1/DC1' initialized to UP/10
    gdnsd[1836]: state of '30.0.0.1/DC2' initialized 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, 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:

haproxy
frontend gslb-fe
  bind 127.0.0.1:8080
  log global
  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
  log global
  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
haproxy
frontend gslb-fe
  bind 127.0.0.1:8080
  log global
  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
  log global
  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 301 Moved Permanently, which would cause the health check to fail:

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 301 217 - - ---- 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 301 217 - - ---- 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) }

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.

; <<>> 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
; <<>> 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

CLI commands Jump to heading

From the CLI, you can see the status and the logs of the GSLB service.

View GSLB logs Jump to heading

To see logs related to GSLB, call the syslog read system command from the CLI.

nix
sudo service syslog read system | fgrep gslb
nix
sudo service syslog read system | fgrep gslb
output
text
Mar 18 10:29:38 aloha01 daemon.info gdnsd[9313]: gdnsd version 3.8.0 @ pid 9313
Mar 18 10:29:38 aloha01 daemon.info gdnsd[9313]: DNS listener threads (2 UDP + 2 TCP) configured for 0.0.0.0:53
output
text
Mar 18 10:29:38 aloha01 daemon.info gdnsd[9313]: gdnsd version 3.8.0 @ pid 9313
Mar 18 10:29:38 aloha01 daemon.info gdnsd[9313]: DNS listener threads (2 UDP + 2 TCP) configured for 0.0.0.0:53

View status of answer records Jump to heading

To see the up / down status of each DNS answer record’s IP address, call the service gslb stats command from the CLI or from the Diagnostic Tools menu on the Tools tab.

  • real_state refers to the up/down status of the IP address based on health checks.
  • state refers to an administrative override value of the IP address’s status (currently not supported).
nix
sudo service gslb stats
nix
sudo service gslb stats
output
json
{
  ...
  "198.51.100.1/DC1": { "state": "UP", "real_state": "UP"},
  "198.51.100.2/DC1": { "state": "UP", "real_state": "UP"},
  "198.51.100.3/DC1": { "state": "UP", "real_state": "UP"},
  "2001:db8::4001/DC1": { "state": "UP", "real_state": "UP"},
  "2001:db8::4002/DC1": { "state": "UP", "real_state": "UP"},
  "2001:db8::4003/DC1": { "state": "UP", "real_state": "UP"},
  "203.0.113.10/DC2": { "state": "UP", "real_state": "UP"},
  "203.0.113.11/DC2": { "state": "UP", "real_state": "UP"},
  "203.0.113.12/DC2": { "state": "UP", "real_state": "UP"},
}
output
json
{
  ...
  "198.51.100.1/DC1": { "state": "UP", "real_state": "UP"},
  "198.51.100.2/DC1": { "state": "UP", "real_state": "UP"},
  "198.51.100.3/DC1": { "state": "UP", "real_state": "UP"},
  "2001:db8::4001/DC1": { "state": "UP", "real_state": "UP"},
  "2001:db8::4002/DC1": { "state": "UP", "real_state": "UP"},
  "2001:db8::4003/DC1": { "state": "UP", "real_state": "UP"},
  "203.0.113.10/DC2": { "state": "UP", "real_state": "UP"},
  "203.0.113.11/DC2": { "state": "UP", "real_state": "UP"},
  "203.0.113.12/DC2": { "state": "UP", "real_state": "UP"},
}

View GSLB information Jump to heading

To see a summary of information regarding the GSLB service, call the service gslb info command.

nix
sudo service gslb info
nix
sudo service gslb info
output
json
{
  "uptime": 899,
  "stats": {
  	"noerror": 0,
  	"refused": 0,
  	"nxdomain": 0,
  	"notimp": 0,
  	"badvers": 0,
  	"formerr": 0,
  	"dropped": 0,
  	"v6": 0,
  	"edns": 0,
  	"edns_clientsub": 0,
  	"edns_do": 0,
  	"edns_cookie_formerr": 0,
  	"edns_cookie_ok": 0,
  	"edns_cookie_init": 0,
  	"edns_cookie_bad": 0
  },
  "udp": {
  	"reqs": 0,
  	"recvfail": 0,
  	"sendfail": 0,
  	"tc": 0,
  	"edns_big": 0,
  	"edns_tc": 0
  },
  "tcp": {
  	"reqs": 0,
  	"recvfail": 0,
  	"sendfail": 0,
  	"conns": 0,
  	"close_c": 0,
  	"close_s_ok": 0,
  	"close_s_err": 0,
  	"close_s_kill": 0,
  	"proxy": 0,
  	"proxy_fail": 0,
  	"dso_estab": 0,
  	"dso_protoerr": 0,
  	"dso_typeni": 0,
  	"acceptfail": 0
  }
}
output
json
{
  "uptime": 899,
  "stats": {
  	"noerror": 0,
  	"refused": 0,
  	"nxdomain": 0,
  	"notimp": 0,
  	"badvers": 0,
  	"formerr": 0,
  	"dropped": 0,
  	"v6": 0,
  	"edns": 0,
  	"edns_clientsub": 0,
  	"edns_do": 0,
  	"edns_cookie_formerr": 0,
  	"edns_cookie_ok": 0,
  	"edns_cookie_init": 0,
  	"edns_cookie_bad": 0
  },
  "udp": {
  	"reqs": 0,
  	"recvfail": 0,
  	"sendfail": 0,
  	"tc": 0,
  	"edns_big": 0,
  	"edns_tc": 0
  },
  "tcp": {
  	"reqs": 0,
  	"recvfail": 0,
  	"sendfail": 0,
  	"conns": 0,
  	"close_c": 0,
  	"close_s_ok": 0,
  	"close_s_err": 0,
  	"close_s_kill": 0,
  	"proxy": 0,
  	"proxy_fail": 0,
  	"dso_estab": 0,
  	"dso_protoerr": 0,
  	"dso_typeni": 0,
  	"acceptfail": 0
  }
}

Reference guide Jump to heading

This section describes the syntax of the zonefile, which you can access by going to the Services tab, clicking [advanced mode], then editing the gslb configuration.

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> ttl <seconds> <RECORD_TYPE> <FIELDS>
text
record <DOMAIN_NAME> ttl <seconds> <RECORD_TYPE> <FIELDS>

Arguments include:

Argument Description
DOMAIN_NAME 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.

A records Jump to heading

An A record maps a domain name to an IPv4 address.

Syntax:

text
record <DOMAIN_NAME string>|@ [ttl <seconds>] A <IPv4_ADDRESS string>
text
record <DOMAIN_NAME string>|@ [ttl <seconds>] A <IPv4_ADDRESS string>
  • IPv4_ADDRESS is the IPv4 address to return.

Example:

text
record www ttl 30 A 203.0.113.1
text
record www ttl 30 A 203.0.113.1

AAAA records Jump to heading

An AAAA record maps a domain name to an IPv6 address.

Syntax:

text
record <DOMAIN_NAME string>|@ [ttl <seconds>] AAAA <IPv6_ADDRESS string>
text
record <DOMAIN_NAME string>|@ [ttl <seconds>] AAAA <IPv6_ADDRESS string>
  • IPv6_ADDRESS is the IPv6 address to return.

Example:

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

CAA records Jump to heading

A CAA record stands for Certificate Authority Authorization. It defines a policy that determines which certificate authorities are authorized to issue certificates for a particular domain name. Several CAA records can share the same name to authorize several authorities.

Syntax:

text
record <DOMAIN_NAME string>|@ [ttl <seconds>] CAA <FLAGS number> <TAG string> <VALUE string>
text
record <DOMAIN_NAME string>|@ [ttl <seconds>] CAA <FLAGS number> <TAG string> <VALUE string>
  • FLAGS is a number between 0 and 255, however only the value 128 is defined and means issuer critical. Usually, set 0.
  • TAG is the CAA policy name, such as issue, issuewild, iodef, contactemail, and contactphone.
  • VALUE is the CAA policy value, enclosed in quotes. It can be an empty string, as in CAA 0 issue "" to forbid any CA from issuing certificates for the name.

Example:

text
record @ CAA 0 issue "letsencrypt.org"
record @ CAA 0 issue "sectigo.com; account=123456"
record @ CAA 0 issuewild ""
record @ CAA 128 iodef "mailto:security@domain.com"
text
record @ CAA 0 issue "letsencrypt.org"
record @ CAA 0 issue "sectigo.com; account=123456"
record @ CAA 0 issuewild ""
record @ CAA 128 iodef "mailto:security@domain.com"

CNAME records Jump to heading

A CNAME record, which stands for Canonical Name, desginates a hostname as an alias for another (canonical) hostname. A common way to use this type of record is to resolve an alias like www.example.com by following the DNS records of example.com.

Syntax:

text
record <DOMAIN_NAME string>|@ [ttl <seconds>] CNAME <TARGET string>
text
record <DOMAIN_NAME string>|@ [ttl <seconds>] CNAME <TARGET string>
  • TARGET is the target, canonical hostname.

Example:

text
record www.example.com. ttl 30 CNAME example.com
text
record www.example.com. ttl 30 CNAME example.com

List records Jump to heading

A list record returns a list of answer-list section names separated by spaces associated with the domain name.

Syntax:

text
record <DOMAIN_NAME string>|@ [ttl <seconds>] list <ANSWER_LIST_NAME string> [<ANSWER_LIST_NAME string>...]
text
record <DOMAIN_NAME string>|@ [ttl <seconds>] list <ANSWER_LIST_NAME string> [<ANSWER_LIST_NAME string>...]

Example:

text
record www2 ttl 30 list london paris amsterdam
text
record www2 ttl 30 list london paris amsterdam

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>] [inter <seconds>] [timeout <seconds>]
  http-check connect [port <PORT number>] [ssl]
  http-check send [uri <URI string>] [hdr host <HEADER_VALUE string>]
  http-check expect [status <STATUS number>,<number>,...]
  tcp-check connect [port <PORT 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>] [inter <seconds>] [timeout <seconds>]
  http-check connect [port <PORT number>] [ssl]
  http-check send [uri <URI string>] [hdr host <HEADER_VALUE string>]
  http-check expect [status <STATUS number>,<number>,...]
  tcp-check connect [port <PORT 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 or HAProxy ALOHA 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 HTTP health check parameters.
tcp-check Set any relevant TCP health check parameters.
answer-record Enter any number of answer-record directives, which denote IP addresses assigned to the datacenter.

Map records Jump to heading

A map record returns a list of geoip-map names separated by spaces associated with the domain name.

Syntax:

text
record <DOMAIN_NAME string>|@ [ttl <seconds>] map <GEOIP_MAP_NAME string> [<GEOIP_MAP_NAME string>...]
text
record <DOMAIN_NAME string>|@ [ttl <seconds>] map <GEOIP_MAP_NAME string> [<GEOIP_MAP_NAME string>...]

Example:

text
record www3 ttl 30 map mymap
text
record www3 ttl 30 map mymap

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_LIST_NAME string> [<ANSWER_LIST_NAME string>...]
  network <SUBNET cidr> <ANSWER_LIST_NAME string> [<ANSWER_LIST_NAME string>...]
text
geoip-map <MAP_NAME string>
  location-base <PATH string>
  location <GEO string|default> <ANSWER_LIST_NAME string> [<ANSWER_LIST_NAME string>...]
  network <SUBNET cidr> <ANSWER_LIST_NAME string> [<ANSWER_LIST_NAME string>...]
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

MX records Jump to heading

An MX (mail exchange) record represents the mailing record for the domain.

Syntax:

text
record <DOMAIN_NAME string>|@ [ttl <seconds>] MX <PRIORITY number> <MAIL_SERVER string>
text
record <DOMAIN_NAME string>|@ [ttl <seconds>] MX <PRIORITY number> <MAIL_SERVER string>
  • PRIORITY indicates the preference or priority of this mail server. Lower values represent higher priority.
  • MAIL_SERVER is the target mail server hostname.

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

NAPTR records Jump to heading

An NAPTR record stands for Name Authority Pointer. It maps a name to a service through a rewrite rule and is mostly used for Session Initiation Protocol (SIP) and E.164 Number to URI Mapping (ENUM) in telephony. Several NAPTR records can share the same name, which is how several services are offered for one name.

Syntax:

text
record <DOMAIN_NAME string>|@ [ttl <seconds>] NAPTR <ORDER number> <PREF number> <FLAGS string> <SERVICES string> <REGEXP string> <REPLACEMENT string>
text
record <DOMAIN_NAME string>|@ [ttl <seconds>] NAPTR <ORDER number> <PREF number> <FLAGS string> <SERVICES string> <REGEXP string> <REPLACEMENT string>
  • ORDER is a number between 0 and 65535; it indicates the processing order, with lower values getting preference.
  • PREF is a number between 0 and 65535; it indicates the preference among records when ORDER is equal.
  • FLAGS is usually one letter: use S when REPLACEMENT is an SRV name, A when it’s a host name, U when REGEXP produces a URI, and P when the rest is protocol specific. Enclose this in quotes.
  • SERVICES indicates the protocol and the resolution service, as in SIP+D2U or E2U+sip. Enclose this in quotes.
  • REGEXP is a regular expression that defines how to rewrite the domain or URI, as in !^.*$!sip:info@domain.com!i. Enclose it in single quotes, which maintains the literal values of backreferences that use backslashes (\1, \2, etc.). The value is limited to 255 characters. When setting REPLACEMENT, set this to an empty string.
  • REPLACEMENT is the replacement domain name. Set it to . when setting REGEXP, since the regular expression supplies the result.

Example:

text
record @ NAPTR 100 10 "S" "SIP+D2U" "" _sip._udp
record @ NAPTR 102 10 "S" "SIP+D2T" "" _sip._tcp
record @ NAPTR 100 10 "U" "E2U+sip" '!^.*$!sip:info@domain.com!i' .
record @ NAPTR 100 10 "U" "E2U+sip" '!^\+1(.*)$!sip:\1@domain.com!i' .
text
record @ NAPTR 100 10 "S" "SIP+D2U" "" _sip._udp
record @ NAPTR 102 10 "S" "SIP+D2T" "" _sip._tcp
record @ NAPTR 100 10 "U" "E2U+sip" '!^.*$!sip:info@domain.com!i' .
record @ NAPTR 100 10 "U" "E2U+sip" '!^\+1(.*)$!sip:\1@domain.com!i' .

NS records Jump to heading

An NS record specifies the authoritative nameservers for a domain. These servers are responsible for providing DNS information for the domain.

Syntax:

text
record <DOMAIN_NAME string>|@ [ttl <seconds>] NS <NAMESERVER string>
text
record <DOMAIN_NAME string>|@ [ttl <seconds>] NS <NAMESERVER string>
  • NAMESERVER is the hostname of the target nameserver. A separate A record will resolve this hostname to an IP address.

Example:

text
record example.com. ttl 30 NS ns1.examplehosting.com 
record example.com. ttl 30 NS ns2.examplehosting.com
text
record example.com. ttl 30 NS ns1.examplehosting.com 
record example.com. ttl 30 NS ns2.examplehosting.com

PTR records Jump to heading

A PTR record maps an IP address to a domain name. It’s short for pointer and is the opposite of an A record, which maps a domain name to an IP address. PTR records enable reverse DNS lookups, facilitating network troubleshooting by showing domain names in trace routes. You’ll add these types of records to a reverse zone, which are zones that have names ending in in-addr.arpa for IPv4 and ip6.arpa for IPv6.

Syntax:

text
record <HOST string> [ttl <seconds>] PTR <DOMAIN_NAME string>
text
record <HOST string> [ttl <seconds>] PTR <DOMAIN_NAME string>
  • RECORD_NAME is the host portion of the IP address. For example, if the IPv4 address is 203.0.113.3/24, then the host portion is 3.
  • DOMAIN_NAME should almost always be absolute, meaning that it ends with a dot. If you miss this, you’ll get a warning. Multiple PTR records can share the same hostname and they’ll all be returned.

Example for the 203.0.113.0/24 network:

zone 113.0.203.in-addr.arpa
  record @ NS ns1.domain.com.
  record 1 PTR ns1.domain.com.
  record 3 ttl 60 PTR mail1.domain.com.
zone 113.0.203.in-addr.arpa
  record @ NS ns1.domain.com.
  record 1 PTR ns1.domain.com.
  record 3 ttl 60 PTR mail1.domain.com.

SOA records Jump to heading

An SOA record means Start of Authority; it 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.

Syntax:

text
record <DOMAIN_NAME string> [ttl <seconds>] <PRIMARY_NAMESERVER string> <RESPONSIBLE_PERSON string> <SERIAL number> <REFRESH number> <RETRY number> <EXPIRE number> <MINIMUM number>
text
record <DOMAIN_NAME string> [ttl <seconds>] <PRIMARY_NAMESERVER string> <RESPONSIBLE_PERSON string> <SERIAL number> <REFRESH number> <RETRY number> <EXPIRE number> <MINIMUM number>
  • PRIMARY_NAMESERVERis the primary authoritative DNS server for the domain where DNS queries for this domain are initially directed.
  • RESPONSIBLE_PERSON is an 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.
  • SERIAL is the serial number, which is incremented each time the zone is updated. This helps in tracking changes to the zone.
  • REFRESH sets how many seconds secondary servers cehck for updates.
  • RETRY sets how many seconds secondary servers wait before retrying a failed update check.
  • EXPIRE sets how many seconds secondary servers keep serving the zone without a successful refresh.
  • MINIMUM sets the negative caching TTL, which is how many seconds resolvers should cache that a requested DNS name or record doesn’t exist.

Example:

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

SRV records Jump to heading

An SRV record advertises the host and the port of a service. You can use them for DNS-based service discovery, wherein they return the hostname of the server hosting the service (the target) and the port where the service is listening. For a tutorial on using SRV records with service discovery, see Service discovery with SRV records.

Syntax:

text
record <RECORD_NAME string> [ttl <seconds>] SRV <PRIORITY number> <WEIGHT number> <PORT number> <TARGET string>
text
record <RECORD_NAME string> [ttl <seconds>] SRV <PRIORITY number> <WEIGHT number> <PORT number> <TARGET string>
  • RECORD_NAME has the form _service._proto.name., where _service is the service’s name; _proto is the protocol (tcp or udp); and name is the domain name, ending with a dot. Several SRV record can share the same name to advertise several hosts for one service.
  • PRIORITY is a number between 0 and 65535 that indicates which host the client should connect to first, with preference going to the host with the lowest priority value.
  • WEIGHT is a number between 0 and 65535 that indicates which host has priority when PRIORITY is equal. A host with a higher weight value is given preference.
  • PORT is a number between 0 and 65535 that indicates the port where the service is listening on the host.
  • TARGET is a the hostname of the server providing the service, ending in a dot. It must resolve to an A or AAAA record, although it can be the name a list or map record from the same zone for a load balanced name.

Example:

text
record _sip._udp   SRV 10 60 5060 sip-a
record _sip._udp   SRV 10 20 5060 sip-b
record _sip._tcp   ttl 60 SRV 20 0 5060 sip-a
record _xmpp._tcp  SRV 5 0 5269 .
text
record _sip._udp   SRV 10 60 5060 sip-a
record _sip._udp   SRV 10 20 5060 sip-b
record _sip._tcp   ttl 60 SRV 20 0 5060 sip-a
record _xmpp._tcp  SRV 5 0 5269 .

TXT records Jump to heading

A TXT record stores arbitrary text associated with a domain name. You can use this type of record to publish verification or policy information, such as:

  • SPF email-sending policy
  • DMARC policy
  • DKIM public-key data
  • Domain ownership verification
  • Configuration information for various services

Syntax:

text
record <RECORD_NAME string>|@ [ttl <seconds>] TXT <string> [<string>]...
text
record <RECORD_NAME string>|@ [ttl <seconds>] TXT <string> [<string>]...
  • RECORD_NAME is a hostname or other name.
  • string is text enclosed by quotes, to allow spaces. A string can be empty, and there’s no limit on the number of strings, but the entire TXT record must be less than 16000 bytes. A single string longer than 255 bytes will be split into several unless the disable_text_autosplit option has been set. Any character is acceptable, since the GSLB module escapes characters as needed.

Example:

text
record @      TXT "v=spf1 include:_spf.domain.com ~all"
record _dmarc TXT "v=DMARC1; p=none; rua=mailto:dmarc@domain.com"
record dkim   TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSq8AM" "IIBCgKCAQEAxyz=="
record check  ttl 60 TXT 'single quotes keep everything literal: \ " #'
text
record @      TXT "v=spf1 include:_spf.domain.com ~all"
record _dmarc TXT "v=DMARC1; p=none; rua=mailto:dmarc@domain.com"
record dkim   TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSq8AM" "IIBCgKCAQEAxyz=="
record check  ttl 60 TXT 'single quotes keep everything literal: \ " #'

Generic records Jump to heading

Any other type of record not otherwise covered falls under this generic category, as prescribed by RFC 3579 Handling of Unknown DNS Resource Record Types.

Syntax:

text
record <RECORD_NAME string>|@ [ttl <seconds>] TYPE<n> \# <RDLENGTH number> <RDATA hex>...
text
record <RECORD_NAME string>|@ [ttl <seconds>] TYPE<n> \# <RDLENGTH number> <RDATA hex>...
  • <n> is the numeric type.
  • RDLENGTH is the number of bytes of RDATA, that is half the number of hexadecimal digits. If set incorrectly, the resulting error will report the correct value.
  • RDATA is the wire format written in hexadecimal. dig prints unknown types in exactly this form, so its output can be pasted here as it is.

Example:

text
# TLSA 3 1 1 <sha256>, the digest is already hexadecimal
record _443._tcp.www TYPE52 \# 35 030101d2abde240d7cd3ee6b4b28c54df034b97983a1d16e8a410e4561cb106618e971
# SSHFP 2 1 <sha1>
record host TYPE44 \# 22 0201aabbccddeeff00112233445566778899aabbccdd
# HTTPS 1 . alpn="h3,h2"
record @ TYPE65 \# 13 00010000010006026833026832
text
# TLSA 3 1 1 <sha256>, the digest is already hexadecimal
record _443._tcp.www TYPE52 \# 35 030101d2abde240d7cd3ee6b4b28c54df034b97983a1d16e8a410e4561cb106618e971
# SSHFP 2 1 <sha1>
record host TYPE44 \# 22 0201aabbccddeeff00112233445566778899aabbccdd
# HTTPS 1 . alpn="h3,h2"
record @ TYPE65 \# 13 00010000010006026833026832

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? Please leave feedback!

Previous page Flows and outflows Next page IP ACLs