pdns/dnsdistdist/docs/manpages/dnsdist.1.rst

   1 dnsdist manual page
   2 ===================
   3
   4 **dnsdist** - tool to balance DNS queries over downstream servers
   5
   6 Synopsis
   7 --------
   8
   9 dnsdist [<option>...] [address]...
  10
  11 Description
  12 -----------
  13
  14 :program:`dnsdist` receives DNS queries and relays them to one or more
  15 downstream servers. It subsequently sends back responses to the original
  16 requestor.
  17
  18 :program:`dnsdist` operates over TCP and UDP, and strives to deliver very high
  19 performance over both.
  20
  21 Currently, queries are sent to the downstream server with the least
  22 outstanding queries. This effectively implies load balancing, making
  23 sure that slower servers get less queries.
  24
  25 If a reply has not come in after a few seconds, it is removed from the
  26 queue, but in the short term, timeouts do cause a server to get less
  27 traffic.
  28
  29 IPv4 and IPv6 operation can be mixed and matched, in other words,
  30 queries coming in over IPv6 could be forwarded to IPv4 and vice versa.
  31
  32 :program:`dnsdist` is scriptable in Lua, see the dnsdist documentation for more
  33 information on this.
  34
  35 Scope
  36 -----
  37
  38 :program:`dnsdist` does not 'think' about DNS queries, it restricts itself to
  39 measuring response times and error codes and routing questions
  40 accordingly. It comes with a very high performance packet-cache.
  41
  42 The goal for dnsdist is to remain simple. If more powerful loadbalancing
  43 is required, dedicated hardware or software is recommended. Linux
  44 Virtual Server for example is often mentioned.
  45
  46 Options
  47 -------
  48
  49 -a <netmask>, --acl <netmask>          Add *netmask* to the ACL.
  50 -C <file>, --config <file>             Load configuration from *file*.
  51 --check-config                         Test the configuration file (which may be set with **--config** or **-C**)
  52                                        for errors. dnsdist will show the errors and exit with a non-zero
  53                                        exit-code when errors are found.
  54 -c <address>, --client <address>       Operate as a client, connect to dnsdist. This will read the dnsdist
  55                                        configuration for the **controlSocket** statement and connect to it.
  56                                        When *address* (with an optional port number) is set, dnsdist will connect
  57                                        to that instead.
  58 -k <key>, --setkey <key>               When operating as a client(**-c**, **--client**), use *key* as
  59                                        shared secret to connect to dnsdist. This should be the same key
  60                                        that is used on the server (set with **setKey()**). Note that this
  61                                        will leak the key into your shell's history. Only available when
  62                                        dnsdist is compiled with libsodium support.
  63 -d, --daemon                           Operate as a daemon.
  64 -e, --execute <command>                Connect to dnsdist and execute *command*.
  65 -h, --help                             Display a helpful message and exit.
  66 -l, --local <address>                  Bind to *address*, Supply as many addresses (using multiple
  67                                        **--local** statements) to listen on as required. Specify IPv4 as
  68                                        0.0.0.0:53 and IPv6 as [::]:53.
  69 --supervised                           Run in foreground, but do not spawn a console. Use this switch to
  70                                        run dnsdist inside a supervisor (use with e.g. systemd and
  71                                        daemontools).
  72 --disable-syslog                       Disable logging to syslog. Use this when running inside a supervisor
  73                                        that handles logging (like systemd). Do not use in combination with
  74                                        **--daemon**.
  75 -p, --pidfile <file>                   Write a pidfile to *file*, works only with **--daemon**.
  76 -u, --uid <uid>                        Change the process user to *uid* after binding sockets. *uid* can be
  77                                        a name or number.
  78 -g, --gid <gid>                        Change the process group to *gid* after binding sockets. *gid* Can
  79                                        be a name or number.
  80 -V, --version                          Show the dnsdist version and exit.
  81 -v, --verbose                          Be verbose.
  82
  83 **address** are any number of downstream DNS servers, in the same syntax as used
  84 with **--local**. If the port is not specified, 53 is used.
  85
  86 Bugs
  87 ----
  88
  89 Right now, the TCP support has some rather arbitrary limits.
  90
  91 Resources
  92 ---------
  93
  94 Website: http://dnsdist.org