HAProxy ALOHA Documentation 15.5

Reference guide

Domain zone

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

Syntax:

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

This example defines a zone for example.com.

zone example.com

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

Time to Live

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

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

Records declared using the record directive provide zone responses.

Syntax:

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

Options include:

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

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.

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

Here's a breakdown of the SOA record's fields:

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

Map a domain name to an IPv4 address.

record www A 203.0.113.1

AAAA records

Map a domain name to an IPv6 address.

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

CNAME records

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

www.example.com. CNAME example.com

NS records

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

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

MX records

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:

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

List records

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

record www2 list london paris amsterdam

Map records

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

record www3 map mymap

Answer list

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:

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) - return all servers, even if they are down (method multi-all)

option

Specify httpchk or tcpchk to monitor the health of servers.

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.

 
answer-list london
  up_threshold 0.8  # 80% threshold for considering a server "up"
  method multi-up  # Use multiple servers that are "up" for load balancing

  # HTTP check options
  option httpchk
  http-check connect
  http-check send uri /healthcheck hdr Host webserver-list.example.com
  http-check expect status 200

  # Define the actual server records with optional weight
  answer-record webserver1 192.168.1.1 weight 2
  answer-record webserver2 192.168.1.2 weight 32

answer-list paris
  up_threshold 0.9  # 90% threshold for considering a server "up"
  method single-rr  # Use a single server in a round-robin fashion

  # TCP check options
  option tcpchk
  tcp-check connect port 8080

  # Define the actual server records
  answer-record webserver1 192.168.2.1
  answer-record webserver2 192.168.2.2

GeoIP map

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:

geoip-map <MAP_NAME string>
  location-base <PATH string>
  location <GEO string|default> <ANSWER-LISTS>
  network <SUBNET cidr> <ANSWER-LISTS>

geoip-map section 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

 
geoip-map mymap
   location-base /path/to/geoip/db  # The path to your GeoIP database file

   # Define location-based rules
   location NA/US/Chicago webserver-list-US  # If the user is in Chicago, US, use the "webserver-list-US" answer-list
   location EU/DE/Berlin webserver-list-EU  # If the user is in Berlin, Germany, use the "webserver-list-EU" answer-list
   location ASIA webserver-list-ASIA  # If the user is anywhere in Asia, use the "webserver-list-ASIA" answer-list
   location default webserver-list-default  # If the user's location is not specified, use the "webserver-list-default" answer-list

   # Define network-based rules
   network 10.0.0.0/24 internal-list  # If the user is coming from the 10.0.0.0/24 subnet, use the "internal-list" answer-list

Next up

Flows