pdns/dnsdistdist/docs/guides/downstreams.rst

   1 Configuring Downstream Servers
   2 ==============================
   3
   4 As dnsdist is a loadbalancer and does not do any DNS resolving or serving by itself, it needs downstream servers.
   5 To add downstream servers, either include them on the command line::
   6
   7     dnsdist -l 130.161.252.29 -a 130.161.0.0/16 8.8.8.8 208.67.222.222 2620:0:ccc::2 2620:0:ccd::2
   8
   9 Or add them to the configuration file:
  10
  11 .. code-block:: lua
  12
  13     setLocal("130.161.252.29:53")
  14     setACL("130.161.0.0/16")
  15     newServer("8.8.8.8")
  16     newServer("208.67.222.222")
  17     newServer("2620:0:ccc::2")
  18     newServer("2620:0:0ccd::2")
  19
  20 These two equivalent configurations give you sane load balancing using a very sensible distribution policy.
  21 Many users will simply be done with this configuration.
  22 It works as well for authoritative as for recursive servers.
  23
  24 .. _Healthcheck:
  25
  26 Healthcheck
  27 -----------
  28 dnsdist uses a health check, sent once every second, to determine the availability of a backend server.
  29
  30 By default, an A query for "a.root-servers.net." is sent.
  31 A different query type, class and target can be specified by passing, respectively, the ``checkType``, ``checkClass`` and ``checkName`` parameters to :func:`newServer`.
  32
  33 The default behavior is to consider any valid response with an RCODE different from ServFail as valid.
  34 If the ``mustResolve`` parameter of :func:`newServer` is set to ``true``, a response will only be considered valid if its RCODE differs from NXDomain, ServFail and Refused.
  35
  36 The number of health check failures before a server is considered down is configurable via the ``maxCheckFailures`` parameter, defaulting to 1.
  37 The CD flag can be set on the query by setting ``setCD`` to true.
  38 e.g.::
  39
  40   newServer({address="192.0.2.1", checkType="AAAA", checkType=DNSClass.CHAOS, checkName="a.root-servers.net.", mustResolve=true})
  41
  42 You can turn on logging of health check errors using the :func:`setVerboseHealthChecks` function.
  43
  44 Since the 1.3.0 release, the ``checkFunction`` option is also supported, taking a ``Lua`` function as parameter. This function receives a DNSName, two integers and a ``DNSHeader`` object (:ref:`DNSHeader`)
  45 representing the QName, QType and QClass of the health check query as well as the DNS header, as they are defined before the function was called. The function must return a DNSName and two integers
  46 representing the new QName, QType and QClass, and can directly modify the ``DNSHeader`` object.
  47
  48 The following example sets the CD flag to true and change the QName to "powerdns.com." and the QType to AAAA while keeping the initial QClass.
  49
  50 .. code-block:: lua
  51
  52     function myHealthCheck(qname, qtype, qclass, dh)
  53       dh:setCD(true)
  54
  55       return newDNSName("powerdns.com."), dnsdist.AAAA, qclass
  56     end
  57
  58     newServer("2620:0:0ccd::2")
  59
  60 Source address selection
  61 ------------------------
  62
  63 In multi-homed setups, it can be useful to be able to select the source address or the outgoing
  64 interface used by dnsdist to contact a downstream server. This can be done by using the `source` parameter::
  65
  66   newServer({address="192.0.2.1", source="192.0.2.127"})
  67   newServer({address="192.0.2.1", source="eth1"})
  68   newServer({address="192.0.2.1", source="192.0.2.127@eth1"})
  69
  70 The supported values for source are:
  71
  72 - an IPv4 or IPv6 address, which must exist on the system
  73 - an interface name
  74 - an IPv4 or IPv6 address followed by '@' then an interface name
  75
  76 Please note that specifying the interface name is only supported on system having `IP_PKTINFO`.