PowerDNS Recursor with dnsdist

Search Marketplace for PowerDNS Recursor with dnsdist, select the SecureAnyCloud publisher, and click Create.

Configure the Network Security Group to allow the transports your clients will use, from your client networks only. Use UDP 53 and TCP 53 for plain DNS, TCP 853 for DNS over TLS and TCP 443 for DNS over HTTPS. Also allow TCP 22 for administration. Both management dashboards stay on loopback and are never exposed.

RG="dns-prod"; LOCATION="eastus"; VM_NAME="resolver1" IMAGE_URN="sac1647283583153:powerdns-recursor-dnsdist:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION"
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:powerdns-recursor-dnsdist:default:latest
az vm create \
  --resource-group "$RG" --name "$VM_NAME" \
  --image "$IMAGE_URN" \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values "$SSH_KEY" \
  --public-ip-sku Standard

Every credential on this appliance is unique to your VM. The first boot generated them. Connect over SSH, then print the credentials file.

sudo cat /root/powerdns-recursor-dnsdist-credentials.txt

The file lists the dnsdist console key, the dnsdist dashboard password and REST API key, the Recursor REST API key and webserver password, the TLS certificate fingerprint, and this instance's addresses. Store them somewhere safe.

Check that both services are running, then confirm which ports are public and which are loopback-only.

sudo systemctl is-active dnsdist.service pdns-recursor.service

Expected output:

active active

Now confirm the topology. dnsdist should own the three public DNS ports. The Recursor and every management surface must be on 127.0.0.1 only.

echo "PUBLIC (dnsdist front door):"
sudo ss -tulnH | awk '{print $1"\t"$4"\t"$5}' | grep -E '(^|\s)(0\.0\.0\.0|\[::\]):(53|443|853)\b' | sort -u -k2
echo "LOOPBACK ONLY (recursor + management):"
sudo ss -tulnH | awk '{print $1"\t"$4"\t"$5}' | grep -E '127\.0\.0\.1:(5300|8082|8083|5199)' | sort -u -k2

0.0.0.0:53, 0.0.0.0:853 and 0.0.0.0:443 belong to dnsdist. 127.0.0.1:5300 is the Recursor, 127.0.0.1:8082 is its REST API, 127.0.0.1:8083 is the dnsdist dashboard and 127.0.0.1:5199 is the dnsdist console. None of these is reachable from the network.

Confirm the versions you are running:

pdns_recursor --version 2>&1 | head -1 dnsdist --version 2>&1 | head -1

These commands query the appliance on its own routable address, exactly as a client on your VNet would. RESOLVER_IP is resolved from the instance itself, so you can paste each block as-is. From a client machine, set it to this VM's address instead.

Plain DNS on port 53:

RESOLVER_IP="$(hostname -I | awk '{print $1}')" dig +short @"$RESOLVER_IP" A example.com

DNS over TLS on port 853. The appliance's certificate is self-signed and unique to your VM. Point kdig at it with +tls-ca, or install your own certificate (Step 9):

RESOLVER_IP="$(hostname -I | awk '{print $1}')" kdig +tls +tls-hostname="$RESOLVER_IP" +tls-ca=/etc/dnsdist/tls/dnsdist.crt \
  +short @"$RESOLVER_IP" -p 853 A example.com

DNS over HTTPS on port 443 at the /dns-query path. The query below is the RFC 8484 wire-format request for example.com A. The response is binary DNS, so the command reads the answer count from the DNS header instead of printing the response.

RESOLVER_IP="$(hostname -I | awk '{print $1}')" DNS_Q="AAABAAABAAAAAAAAB2V4YW1wbGUDY29tAAABAAE"
CODE=$(curl -sk -o /tmp/doh.bin -w '%{http_code}' -m 15 \
  -H 'accept: application/dns-message' \
  "https://${RESOLVER_IP}/dns-query?dns=${DNS_Q}")
echo "HTTP $CODE answer records: $(od -An -tu1 -j6 -N2 /tmp/doh.bin | awk '{print $1*256+$2}')" rm -f /tmp/doh.bin

A healthy appliance returns HTTP 200 with one or more answer records. An answer count of 0 means the query reached dnsdist but resolution failed. In that case, check outbound UDP 53 from the VM to the internet.

You can also confirm that dnsdist sees the Recursor backend as healthy. Use the per-instance console key:

CONSOLE_KEY=$(sudo grep '^dnsdist.console.key=' /root/powerdns-recursor-dnsdist-credentials.txt | cut -d= -f2-) printf "setKey('%s')\n" "$CONSOLE_KEY" | sudo tee /run/ck.conf >/dev/null
sudo chmod 600 /run/ck.conf
sudo dnsdist -C /run/ck.conf -c 127.0.0.1:5199 -e 'showServers()'
sudo rm -f /run/ck.conf

The powerdns-recursor backend at 127.0.0.1:5300 should report state up.

The dnsdist dashboard shows live queries per second, per-transport latency, backend health and the active access control list. It is bound to loopback, so open an SSH tunnel from your workstation:

ssh -L 8083:127.0.0.1:8083 azureuser@YOUR_VM_ADDRESS

Then open http://127.0.0.1:8083/ and sign in with user admin and the dnsdist.webserver.password value from the credentials file.

The header line summarises the appliance at a glance. It shows total questions answered, current QPS, ACL drops, average response time per transport (UDP, TCP, DoT, DoH), the listening ports and the exact ACL in force.

The Recursor has its own status dashboard on 127.0.0.1:8082. It shows resolver-side metrics: query rate, cache hit rate, CPU, and rings of the most-queried domains and the busiest clients. Tunnel to it the same way:

ssh -L 8082:127.0.0.1:8082 azureuser@YOUR_VM_ADDRESS

Open http://127.0.0.1:8082/ and sign in with user admin and the powerdns.recursor.webserver.password value.

The Queries and Remotes rings are the quickest way to see what your clients are resolving. Every query arrives through dnsdist, so the only remote you will see is 127.0.0.1. This is the front door working as designed.

Out of the box, the appliance answers loopback and the RFC1918 private ranges only. View the shipped ACL:

grep -A 11 '^setACL' /etc/dnsdist/dnsdist.conf

If your clients are already inside 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16, which covers most Azure VNets, there is nothing to change. Confirm your VNet range first:

hostname -I

To add a client range that is not already covered, edit the setACL({...}) list in /etc/dnsdist/dnsdist.conf and add your subnet as a new quoted entry:

setACL({ '127.0.0.0/8', '10.0.0.0/8', ... '203.0.113.0/24', <-- your client subnet })

Then apply it:

sudo systemctl reload dnsdist

Never add 0.0.0.0/0 or ::/0. That turns this instance into an open resolver, an internet-wide DNS amplification reflector. Attackers use such reflectors to DDoS third parties with your bandwidth and your IP address, and your provider may null-route the instance. The appliance refuses to start if it detects a default route in the ACL. Always restrict the ACL to the client networks you operate.

Restrict access at the Network Security Group as well as in dnsdist. Two independent layers are the right posture for anything that answers DNS.

The DoT and DoH certificate is self-signed and unique to your VM. Clients must either trust /etc/dnsdist/tls/dnsdist.crt or pin its fingerprint:

sudo openssl x509 -in /etc/dnsdist/tls/dnsdist.crt -noout -fingerprint -sha256

For clients that expect a publicly trusted certificate, replace the key pair with your own from your CA or an ACME client. Keep the same paths and ownership, then reload:

sudo install -o root -g _dnsdist -m 0644 /path/to/fullchain.pem /etc/dnsdist/tls/dnsdist.crt
sudo install -o root -g _dnsdist -m 0640 /path/to/privkey.pem /etc/dnsdist/tls/dnsdist.key
sudo systemctl reload dnsdist

• No shipped credentials. Every key, password and certificate on this appliance was generated on this VM's first boot. Nothing is shared with any other SecureAnyCloud instance.
• Both daemons fail closed. dnsdist.service and pdns-recursor.service each carry a ConditionPathExists gate on their per-VM secrets. Each also has a start-time guard that refuses to run if a published upstream example credential is in effect, if the console key is too weak, if the ACL contains a default route, or if a management surface is not loopback-bound. You can run that guard yourself at any time:

sudo /usr/local/sbin/sac-dns-secret-guard.sh && echo "secrets in effect are unique to this VM"

• Management surfaces are loopback-only. Neither dashboard, neither REST API, nor the dnsdist console is reachable from the network. Reach them over SSH tunnels, as in Steps 6 and 7.
• Secret files are root-owned. The credentials file is 0600 root:root. The dnsdist and Recursor secret drop-ins and the TLS private key are 0640, readable only by the daemon that needs them.

sudo ls -l /root/powerdns-recursor-dnsdist-credentials.txt /etc/dnsdist/tls/dnsdist.key

Reload dnsdist after any configuration change. The reload re-reads the configuration without dropping service.

sudo systemctl reload dnsdist

Check the logs for either daemon.

sudo journalctl -u dnsdist.service --no-pager | tail -20

sudo journalctl -u pdns-recursor.service --no-pager | tail -20

Unattended security upgrades are enabled, so both packages keep receiving updates from the official PowerDNS repositories on your running VM.