DNSDIST(1)

💅 DNSDIST(1) — the dnsdist manual, bestie edition

okay so this is the manual page for dnsdist, from section 1 of the manual (that's the "user commands" section, iykyk). it's a DNS and DoS aware, scriptable loadbalancer and honestly? she's iconic. let's get into it 🎀

---

✨ NAME ✨

dnsdist — a DNS and DoS aware, scriptable loadbalancer 💅

🦋 SYNOPSIS 🦋

dnsdist [<option>...] [address]...

🌸 DESCRIPTION 🌸

okay so here's the whole vibe: dnsdist receives DNS queries and relays them to one or more downstream servers. then it sends the responses right back to whoever asked originally. main character energy, fr fr.

she operates over TCP and UDP, and she strives to deliver very high performance over both. no cap, that's the goal.

right now, queries get sent to the downstream server with the least outstanding queries. which is lowkey just load balancing with extra steps — it makes sure slower servers get fewer queries. love that for us 🫶

if a reply hasn't come in after a few seconds, it gets removed from the queue. but heads up, in the short term, timeouts do cause a server to get less traffic. so like, ghosting has consequences 💀

IPv4 and IPv6 operation can be mixed and matched — in other words, queries coming in over IPv6 could be forwarded to IPv4 and vice versa. she's flexible like that ✨

and she's scriptable in Lua! see the dnsdist documentation for more info on that.

🔥 SCOPE 🔥

real talk: dnsdist does not 'think' about DNS queries. she restricts herself to measuring response times and error codes and routing questions accordingly. that's it. that's the job. she also comes with a very high performance packet-cache 👑

the goal for dnsdist is to remain simple. if you need more powerful loadbalancing, dedicated hardware or software is recommended — Linux Virtual Server for example is often mentioned. know your limits bestie 🎀

🌈 OPTIONS 🌈

• -a <netmask>, --acl <netmask> — add netmask to the ACL.
• -C <file>, --config <file> — load configuration from file.
• --check-config — test the configuration file (which may be set with --config or -C) for errors. dnsdist will show the errors and exit with a non-zero exit-code when errors are found.
• -c <address>, --client <address> — operate as a client, connect to dnsdist. this will read the dnsdist configuration for the controlSocket statement and connect to it. when address (with an optional port number) is set, dnsdist will connect to that instead.
• -k <key>, --setkey <key> — when operating as a client (-c, --client), use key as shared secret to connect to dnsdist. this should be the same key that is used on the server (set with setKey()). ⚠️ note that this will leak the key into your shell's history and into the systems running process list. only available when dnsdist is compiled with libsodium or libcrypto support.
• -e, --execute <command> — connect to dnsdist and execute command.
• -h, --help — display a helpful message and exit.
• -l, --local <address> — bind to address. supply as many addresses (using multiple --local statements) to listen on as required. specify IPv4 as 0.0.0.0:53 and IPv6 as [::]:53.
• --supervised — run in foreground, but do not spawn a console. use this switch to run dnsdist inside a supervisor (use with e.g. systemd and daemontools).
• --disable-syslog — disable logging to syslog. use this when running inside a supervisor that handles logging (like systemd).
• --log-timestamps — prepend timestamps to messages logged to standard out.
• --structured-logging <true|false> — whether to enable structured logging.
• --structured-logging-backend <backend> — the backend to use when structured logging is enabled. supported values are 'default', 'json' and 'systemd-journal'.
• -u, --uid <uid> — change the process user to uid after binding sockets. uid can be a name or number.
• -g, --gid <gid> — change the process group to gid after binding sockets. gid can be a name or number.
• -V, --version — show the dnsdist version and exit.
• -v, --verbose — be verbose.

and one more thing that isn't a flag but you gotta know about:

address are any number of downstream DNS servers, in the same syntax as used with --local. if the port is not specified, 53 is used. 🍓

💀 BUGS 💀

right now, the TCP support has some rather arbitrary limits. yeah. we know. it's giving "we'll fix it later" 🙈

⭐ RESOURCES ⭐

website: https://dnsdist.org

💜 AUTHOR 💜

PowerDNS.COM BV and its contributors 🫶

👑 COPYRIGHT 👑

PowerDNS.COM BV and its contributors

---

and that's the whole page bestie!! mwah 💋 this shipped as part of the dnsdist docs, dated Oct 12, 2026 — go slay some queries ✨🎀