Quick Start¶
This page walks you through the shortest path to getting ShadowDNS running: building from source, preparing the GeoIP databases, and starting the service.
Prerequisites¶
- Go 1.26+
- MaxMind GeoLite2 databases (Country + ASN, see step 3 — only needed when views use
geoiprules) - An existing BIND configuration (
named.confand zone files)
1. Get the Source¶
2. Build¶
The resulting binary is located at bin/shadowdns-<GOOS>-<GOARCH> (e.g., bin/shadowdns-linux-amd64 on Linux/amd64, bin/shadowdns-darwin-arm64 on Apple Silicon).
3. Prepare the GeoIP Databases¶
ShadowDNS reads the mmdb directory from the geoip-directory option in named.conf (e.g., /usr/local/share/GeoIP/). When geoip-directory is set, the following two files must exist — if either is missing, startup is refused:
Download them from MaxMind. If no view uses geoip country / geoip asnum rules, leave geoip-directory unset and skip this step — ShadowDNS then starts without any mmdb files. See GeoIP Databases for details.
4. Start ShadowDNS¶
Use the binary produced in step 2 (the example below assumes linux/amd64):
ShadowDNS listens on :53 (UDP and TCP) by default; this can be overridden with --listen.
For the contents and format of shadowdns.yaml, see shadowdns.yaml Configuration.
5. Validate the Configuration with --dry-run¶
Before starting for real, it is recommended to first verify with --dry-run that all zone files parse correctly and the GeoIP databases are readable:
./bin/shadowdns-linux-amd64 \
--named-conf /etc/bind/named.conf \
--config /etc/bind/shadowdns.yaml \
--dry-run
--dry-run loads the configuration and zones, prints a summary, and exits immediately without opening any listener. An exit code of 0 means the configuration is valid.
Next Steps¶
- Installation — deploy to a Debian/Ubuntu host with the
.debpackage, managed by systemd - CLI Reference — complete flag and subcommand documentation
- Migrating from BIND — the full operational guide for production cutover