This guide covers installation of dnsdist on all major Linux distributions. Choose the appropriate section for your distribution.
Version Note:
- Version 2.0.x (Current stable: 2.0.2) - YAML configuration support (requires Rust), Lua configuration
- Version 2.1.0-alpha1 (January 2026) - YAML configuration default, OpenTelemetry support, structured logging
# Install from distribution repositories
sudo apt update
sudo apt install dnsdist
# Start and enable
sudo systemctl enable --now dnsdist
# Verify installation
sudo systemctl status dnsdist
# Enable EPEL repository
sudo dnf install -y epel-release
# Install dnsdist
sudo dnf install dnsdist
# Start and enable
sudo systemctl enable --now dnsdist
Supported Versions:
# 1. Update package list
sudo apt update
# 2. Install dnsdist
sudo apt install dnsdist
# 3. Start and enable service
sudo systemctl enable --now dnsdist
# 4. Verify installation
sudo systemctl status dnsdist
# 5. Check version
dnsdist --version
Note: Distribution repositories may contain older versions. For the latest features, use the PowerDNS repository.
For Latest Version:
# 1. Install prerequisites
sudo apt install -y curl gnupg apt-transport-https
# 2. Add PowerDNS GPG key
curl -fsSL https://repo.powerdns.com/FD380FBB-pub.asc | \
sudo tee /etc/apt/keyrings/pdns-archive-keyring.gpg
# 3. Add PowerDNS repository
echo "deb [signed-by=/etc/apt/keyrings/pdns-archive-keyring.gpg] https://repo.powerdns.com/ubuntu $(lsb_release -cs)-dnsdist-20 main" | \
sudo tee /etc/apt/sources.list.d/powerdns.list
# 4. Update package list
sudo apt update
# 5. Install latest dnsdist
sudo apt install dnsdist
# 6. Start and enable service
sudo systemctl enable --now dnsdist
# 7. Verify installation
dnsdist --version
/etc/dnsdist/dnsdist.conf (traditional Lua)/etc/dnsdist/dnsdist.yml/etc/dnsdist/certs/journalctl -u dnsdistSupported Versions:
# 1. Enable EPEL repository
sudo dnf install -y epel-release
# 2. Install dnsdist
sudo dnf install dnsdist
# 3. Start and enable service
sudo systemctl enable --now dnsdist
# 4. Verify installation
dnsdist --version
For Latest Version:
# 1. Add PowerDNS repository
curl -fsSL https://repo.powerdns.com/repo-files/el-dnsdist-20.repo | \
sudo tee /etc/yum.repos.d/powerdns-dnsdist.repo
# 2. Install dnsdist
sudo dnf install dnsdist
# 3. Start and enable service
sudo systemctl enable --now dnsdist
# 4. Verify installation
dnsdist --version
/etc/dnsdist/dnsdist.conf/etc/dnsdist/dnsdist.yml/var/cache/dnsdist/journalctl -u dnsdist -f# Install from binary package
pkg install dnsdist
# Or build from ports
cd /usr/ports/dns/dnsdist
make install clean
# Enable service
sysrc dnsdist_enable="YES"
service dnsdist start
/usr/local/etc/dnsdist/dnsdist.conf/var/log/dnsdist.logRequired Dependencies:
| Component | Minimum Version |
|---|---|
| Compiler | C++17 support (GCC 7+, Clang 5+) |
| Build System | GNU make or meson + ninja |
| Python | 3.x with YAML module |
| Boost | 1.60+ |
| Lua | 5.1+ or LuaJIT 2.0+ |
| Editline | libedit |
Optional Dependencies:
| Library | Feature |
|---|---|
| GnuTLS / OpenSSL | DoT and DoH support |
| libfstrm | dnstap support |
| libsodium | DNSCrypt support |
| quiche | DoQ and DoH3 support |
| nghttp2 | DoH support |
| LMDB | LMDB support |
| net-snmp | SNMP support |
| libcap | Capabilities support |
sudo apt install -y build-essential autoconf automake libtool \
libboost-all-dev liblua5.1-dev libedit-dev \
libssl-dev libsodium-dev libnghttp2-dev \
libfstrm-dev liblmdb-dev libsnmp-dev \
libcap-dev pkg-config python3-yaml
sudo dnf install -y gcc-c++ autoconf automake libtool \
boost-devel lua-devel libedit-devel \
openssl-devel libsodium-devel nghttp2-devel \
libfstrm-devel lmdb-devel net-snmp-devel \
libcap-devel pkg-config python3-pyyaml
# 1. Clone repository
git clone https://github.com/PowerDNS/pdns.git
cd pdns/pdns/dnsdistdist
# 2. Generate build files
autoreconf -i
# 3. Configure
./configure \
--with-lua=lua5.1 \
--with-openssl \
--with-libsodium \
--with-nghttp2
# 4. Build
make -j$(nproc)
# 5. Install
sudo make install
# 6. Update library cache
sudo ldconfig
# 7. Verify installation
dnsdist --version
# 1. Clone repository
git clone https://github.com/PowerDNS/pdns.git
cd pdns/pdns/dnsdistdist
# 2. Setup build directory
meson setup build
# 3. Configure (optional)
meson configure build \
-Dlua=lua5.1 \
-Dopenssl=enabled \
-Dlibsodium=enabled
# 4. Build
meson compile -C build
# 5. Install
sudo meson install -C build
# 6. Verify
dnsdist --version
Basic Lua Configuration (/etc/dnsdist/dnsdist.conf):
-- Listen on standard DNS port
addLocal("0.0.0.0:53")
addLocal(":::53")
-- Define backend servers
newServer{address="192.168.1.10:53"}
newServer{address="192.168.1.11:53"}
-- Set load balancing policy
setServerPolicy(roundrobin)
-- Web interface for statistics
webserver("127.0.0.1:8083", "secure_password")
Basic YAML Configuration (v2.0+, /etc/dnsdist/dnsdist.yml):
servers:
- address: "192.168.1.10:53"
- address: "192.168.1.11:53"
listen:
- "0.0.0.0:53"
- ":::53"
load_balancing:
policy: roundrobin
webserver:
address: "127.0.0.1:8083"
password: "secure_password"
# Check configuration syntax
sudo dnsdist --check-config
# Or test configuration
sudo dnsdist --config=/etc/dnsdist/dnsdist.conf --check
# Start service
sudo systemctl start dnsdist
# Enable on boot
sudo systemctl enable dnsdist
# Check status
sudo systemctl status dnsdist
# Test basic resolution
dig @127.0.0.1 example.com
# Test TCP
dig @127.0.0.1 example.com +tcp
# Check backend status
sudo dnsdist -e "showServers()"
# UFW (Ubuntu/Debian)
sudo ufw allow 53/tcp
sudo ufw allow 53/udp
sudo ufw allow 8083/tcp # Web interface (restrict in production)
# firewalld (Fedora/RHEL)
sudo firewall-cmd --permanent --add-service=dns
sudo firewall-cmd --permanent --add-port=8083/tcp
sudo firewall-cmd --reload
# Check logs
sudo journalctl -u dnsdist -f
# Check configuration
sudo dnsdist --check-config
# Verify file permissions
ls -la /etc/dnsdist/
Common issues:
Port 53 already in use:
sudo ss -tlnp | grep :53
sudo systemctl stop systemd-resolved # If conflicting
Configuration syntax errors:
sudo dnsdist --check-config
# Review error messages
Permission issues:
sudo chown -R dnsdist:dnsdist /etc/dnsdist/
sudo chown -R dnsdist:dnsdist /var/cache/dnsdist/
# Connect to console
sudo dnsdist
# Check backend status
showServers()
# View statistics
showStats()
# Connect to console
sudo dnsdist
# Check backend latency
showServers()
# View query statistics
showStats()
# Validate YAML configuration (v2.0+)
sudo dnsdist --check-config
# Test with specific config file
sudo dnsdist --config=/etc/dnsdist/dnsdist.yml --check
# View current configuration
sudo dnsdist -e "showConfig()"
# Update package list
sudo apt update
# Upgrade dnsdist
sudo apt install --only-upgrade dnsdist
# Restart service
sudo systemctl restart dnsdist
# Verify version
dnsdist --version
sudo dnf upgrade dnsdist
sudo systemctl restart dnsdist
Migrating from version 1.x to 2.x:
# 1. Backup current configuration
sudo cp /etc/dnsdist/dnsdist.conf /etc/dnsdist/dnsdist.conf.backup
# 2. Review breaking changes
# - Lua API changes
# - Deprecated functions removed
# - New default behaviors
# 3. Upgrade package
sudo apt install --only-upgrade dnsdist
# 4. Test configuration
sudo dnsdist --check-config
# 5. Restart service
sudo systemctl restart dnsdist
⚠️ Warning: Version 2.1.0-alpha1 introduces breaking changes:
- YAML configuration is now default (
dnsdist.yml)- h2o library support for DoH removed (nghttp2 only)
- OpenTelemetry support added
- Structured logging added
# 1. Backup configuration
sudo cp /etc/dnsdist/dnsdist.conf /etc/dnsdist/dnsdist.conf.backup
sudo cp /etc/dnsdist/dnsdist.yml /etc/dnsdist/dnsdist.yml.backup 2>/dev/null || true
# 2. Test in staging environment first
# 3. Upgrade
sudo apt install --only-upgrade dnsdist
# 4. Convert configuration if needed
# YAML format now preferred
# 5. Validate
sudo dnsdist --check-config
# 6. Restart
sudo systemctl restart dnsdist
Need professional assistance with your DNS load balancing infrastructure? Our team provides:
Get in touch: office@linux-server-admin.com | Contact Page