dnsdist: Clarify how the different load-balancing policies work

diff --git a/pdns/dnsdistdist/docs/guides/serverselection.rst b/pdns/dnsdistdist/docs/guides/serverselection.rst
index 6cf14bed6fecea7e66e555fecb36fa14184c5cca..f1f0c6d882d7ef7077db5d51fcdffda5c24a1cef 100644 (file)
--- a/pdns/dnsdistdist/docs/guides/serverselection.rst
+++ b/pdns/dnsdistdist/docs/guides/serverselection.rst
@@ -2,6 +2,8 @@ Loadbalancing and Server Policies
 =================================
 
 :program:`dnsdist` selects the server (if there are multiple eligable) to send queries to based on the configured policy.
+Only servers that are marked as 'up', either forced so by the administrator or as the result of the last health check, might
+be selected.
 
 Built-in Policies
 -----------------
@@ -9,12 +11,17 @@ Built-in Policies
 ``leastOutstanding``
 ~~~~~~~~~~~~~~~~~~~~
 
-The default load balancing policy is called ``leastOutstanding``, which means the server with the least queries 'in the air' is picked (and within those, the one with the lowest order, and within those, the one with the lowest latency).
+The default load balancing policy is called ``leastOutstanding``, which means the server with the least queries 'in the air' is picked.
+The exact selection algorithm is:
+
+- pick the server with the least queries 'in the air' ;
+- in case of a tie, pick the one with the lowest configured 'order' ;
+- in case of a tie, pick the one with the lowest measured latency (over an average on the last 128 queries answered by that server).
 
 ``firstAvailable``
 ~~~~~~~~~~~~~~~~~~
 
-The ``firstAvailable`` policy, picks the first server that has not exceeded its QPS limit.
+The ``firstAvailable`` policy, picks the first available server that has not exceeded its QPS limit, ordered by increasing 'order'.
 If all servers are above their QPS limit, a server is selected based on the ``leastOutstanding`` policy.
 For now this is the only policy using the QPS limit.
 
@@ -23,10 +30,14 @@ For now this is the only policy using the QPS limit.
 
 A further policy, ``wrandom`` assigns queries randomly, but based on the weight parameter passed to :func:`newServer`.
 
+For example, if two servers are available, the first one with a weigth of 2 and the second one with a weight of 1 (the default), the
+first one should get two thirds of the incoming queries and the second one the remaining third.
+
 ``whashed``
 ~~~~~~~~~~~
 
 ``whashed`` is a similar weighted policy, but assigns questions with identical hash to identical servers, allowing for better cache concentration ('sticky queries').
+The current hash algorithm is based on the qname of the query.
 
 .. function:: setWHashedPertubation(value)
 

diff --git a/pdns/dnsdistdist/docs/reference/config.rst b/pdns/dnsdistdist/docs/reference/config.rst
index 108a70f2f7b8a6cf5766c97c6242530b9e73a272..85f257ce788d1038740bc81e336978c9bccdb666 100644 (file)
--- a/pdns/dnsdistdist/docs/reference/config.rst
+++ b/pdns/dnsdistdist/docs/reference/config.rst
@@ -206,9 +206,9 @@ Servers
 
     newServer({
       address="IP:PORT",     -- IP and PORT of the backend server (mandatory)
-      qps=NUM,               -- Limit the number of queries per second to NUM
-      order=NUM,             -- The order of this server
-      weight=NUM,            -- The weight of this server
+      qps=NUM,               -- Limit the number of queries per second to NUM, when using the `firstAvailable` policy
+      order=NUM,             -- The order of this server, used by the `leastOustanding` and `firstAvailable` policies
+      weight=NUM,            -- The weight of this server, used by the `wrandom` and `whashed` policies
       pool=STRING|{STRING},  -- The pools this server belongs to (unset or empty string means default pool) as a string or table of strings
       retries=NUM,           -- The number of TCP connection attempts to the backend, for a given query
       tcpConnectTimeout=NUM, -- The timeout (in seconds) of a TCP connection attempt