projects / thirdparty / pdns.git / blame
| Commit | Line | Data |
|---|---|---|
| 20d81666 PL |
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 |