DOC: DNS documentation updated
More information regarding DNS resolution:
- behavior in case of errors
- behavior when multiple name servers are configured in a resolvers
section
- when a retry is performed
- when a query type change is performed
- make it clear that DNS resolution requires health checking enabled
on the server
diff --git a/doc/configuration.txt b/doc/configuration.txt
index 490a34d..40cd6df 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -10223,8 +10223,14 @@
resolvers <id>
Points to an existing "resolvers" section to resolve current server's
hostname.
+ In order to be operational, DNS resolution requires that health check is
+ enabled on the server. Actually, health checks triggers the DNS resolution.
+ You must precise one 'resolvers' parameter on each server line where DNS
+ resolution is required.
- Example: server s1 app1.domain.com:80 resolvers mydns
+ Supported in default-server: No
+
+ Example: server s1 app1.domain.com:80 check resolvers mydns
See also chapter 5.3
@@ -10390,9 +10396,9 @@
5.3. Server IP address resolution using DNS
-------------------------------------------
-HAProxy allows using a host name to be resolved to find out what is the server
-IP address. By default, HAProxy resolves the name when parsing the
-configuration, at startup.
+HAProxy allows using a host name on the server line to retrieve its IP address
+using name servers. By default, HAProxy resolves the name when parsing the
+configuration file, at startup and cache the result for the process' life.
This is not sufficient in some cases, such as in Amazon where a server's IP
can change after a reboot or an ELB Virtual IP can change based on current
workload.
@@ -10401,6 +10407,9 @@
Whether run time server name resolution has been enable or not, HAProxy will
carry on doing the first resolution when parsing the configuration.
+Bear in mind that DNS resolution is triggered by health checks. This makes
+health checks mandatory to allow DNS resolution.
+
5.3.1. Global overview
----------------------
@@ -10437,6 +10446,47 @@
There can be as many as resolvers section as needed. Each section can contain
many name servers.
+When multiple name servers are configured in a resolvers section, then HAProxy
+uses the first valid response. In case of invalid responses, only the last one
+is treated. Purpose is to give the chance to a slow server to deliver a valid
+answer after a fast faulty or outdated server.
+
+When each server returns a different error type, then only the last error is
+used by HAProxy to decide what type of behavior to apply.
+
+Two types of behavior can be applied:
+ 1. stop DNS resolution
+ 2. replay the DNS query with a new query type
+ In such case, the following types are applied in this exact order:
+ 1. ANY query type
+ 2. query type corresponding to family pointed by resolve-prefer
+ server's parameter
+ 3. remaining family type
+
+HAProxy stops DNS resolution when the following errors occur:
+ - invalid DNS response packet
+ - wrong name in the query section of the response
+ - NX domain
+ - Query refused by server
+ - CNAME not pointing to an IP address
+
+HAProxy tries a new query type when the following errors occur:
+ - no Answer records in the response
+ - DNS response truncated
+ - Error in DNS response
+ - No expected DNS records found in the response
+ - name server timeout
+
+For example, with 2 name servers configured in a resolvers section:
+ - first response is valid and is applied directly, second response is ignored
+ - first response is invalid and second one is valid, then second response is
+ applied;
+ - first response is a NX domain and second one a truncated response, then
+ HAProxy replays the query with a new type;
+ - first response is truncated and second one is a NX Domain, then HAProxy
+ stops resolution.
+
+
resolvers <resolvers id>
Creates a new name server list labelled <resolvers id>
@@ -10467,6 +10517,10 @@
giving up.
Default value: 3
+ A retry occurs on name server timeout or when the full sequence of DNS query
+ type failover is over and we need to start up from the default ANY query
+ type.
+
timeout <event> <time>
Defines timeouts related to name resolution
<event> : the event on which the <time> timeout period applies to.