Loadbalancing and Server Policies

dnsdist selects the server (if there are multiple eligible) 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


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


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.


A further policy, wrandom assigns queries randomly, but based on the weight parameter passed to newServer().

For example, if two servers are available, the first one with a weight 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 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.


Set the hash perturbation value to be used in the whashed policy instead of a random one, allowing to have consistent whashed results on different instances.


chashed is a consistent hashing distribution policy. Identical questions with identical hashes will be distributed to the same servers. But unlike the whashed policy, this distribution will keep consistent over time. Adding or removing servers will only remap a small part of the queries.

You can also set the hash perturbation value, see setWHashedPertubation(). To achieve consistent distribution over dnsdist restarts, you will also need to explicitly set the backend’s UUIDs with the id option of newServer(). You can get the current UUIDs of your backends by calling showServers() with the showUUIDs=true option.


The last available policy is roundrobin, which indiscriminately sends each query to the next server that is up. If all servers are down, the policy will still select one server by default. Setting setRoundRobinFailOnNoServer() to true will change this behavior.

Lua server policies

If you don’t like the default policies you can create your own, like this for example:

function luaroundrobin(servers, dq)
     return servers[1+(counter % #servers)]

setServerPolicyLua("luaroundrobin", luaroundrobin)

Incidentally, this is similar to setting: setServerPolicy(roundrobin) which uses the C++ based roundrobin policy.


newServer({address="", pool="numbered"})

function splitSetup(servers, dq)
  if(string.match(dq.qname:toString(), "%d"))
    print("numbered pool")
    return leastOutstanding.policy(getPoolServers("numbered"), dq)
    print("standard pool")
    return leastOutstanding.policy(servers, dq)

setServerPolicyLua("splitsetup", splitSetup)

ServerPolicy Objects

class ServerPolicy

This represents a server policy. The built-in policies are of this type

ServerPolicy.policy(servers, dq) → Server

Run the policy to receive the server it has selected.



newServerPolicy(name, function) → ServerPolicy

Create a policy object from a Lua function. function must match the prototype for ServerPolicy.policy().

  • name (string) – Name of the policy
  • function (string) – The function to call for this policy

Set server selection policy to policy.

Parameters:policy (ServerPolicy) – The policy to use
setServerPolicyLua(name, function)

Set server selection policy to one named name` and provided by function.

  • name (string) – name for this policy
  • function (string) – name of the function

If set, return a ServFail when no servers are available, instead of the default behaviour of dropping the query.

Parameters:value (bool) – whether to return a servfail instead of dropping the query
setPoolServerPolicy(policy, pool)

Set the server selection policy for pool to policy.

  • policy (ServerPolicy) – The policy to apply
  • pool (string) – Name of the pool
setPoolServerPolicyLua(name, function, pool)

Set the server selection policy for pool to one named name and provided by function.

  • name (string) – name for this policy
  • function (string) – name of the function
  • pool (string) – Name of the pool

New in version 1.4.0.

By default the roundrobin load-balancing policy will still try to select a backend even if all backends are currently down. Setting this to true will make the policy fail and return that no server is available instead.

Parameters:value (bool) – whether to fail when all servers are down

Print server selection policy for pool.

Parameters:pool (string) – The pool to print the policy for