Testing

Verify your blockasaurus server is working correctly

After setting up blockasaurus, you’ll want to verify that DNS resolution works, that blocked domains are actually blocked, and that encrypted DNS (DoT/DoH) is functioning if configured.

In the examples below, replace SERVER_IP with your blockasaurus server’s IP address and dns.example.com with your configured domain.

Plain DNS (UDP/TCP)

Plain DNS is the simplest to test. Every operating system includes tools for this.

dig

dig is the standard DNS debugging tool on Linux and macOS.

Basic query

# Query blockasaurus for an A record
dig @SERVER_IP example.com

# Short output (just the answer)
dig @SERVER_IP example.com +short

Verify a domain is blocked

# If using Zero IP block type, you'll get 0.0.0.0
dig @SERVER_IP ads.doubleclick.net +short
# Expected: 0.0.0.0

# If using NXDOMAIN block type, you'll get NXDOMAIN
dig @SERVER_IP ads.doubleclick.net
# Look for: status: NXDOMAIN

Query specific record types

# AAAA (IPv6) record
dig @SERVER_IP example.com AAAA +short

# MX record
dig @SERVER_IP example.com MX +short

# Custom DNS entry
dig @SERVER_IP nas.home +short
# Expected: 192.168.1.50 (or whatever you configured)

nslookup

Available on Windows, macOS, and Linux:

# Basic query
nslookup example.com SERVER_IP

# Verify blocking
nslookup ads.doubleclick.net SERVER_IP

host

Simple and available on most Unix systems:

# Basic query
host example.com SERVER_IP

# Reverse lookup
host 192.168.1.50 SERVER_IP

PowerShell (Windows)

# Using Resolve-DnsName
Resolve-DnsName -Name example.com -Server SERVER_IP

# Verify blocking
Resolve-DnsName -Name ads.doubleclick.net -Server SERVER_IP

DNS-over-TLS (DoT)

DoT encrypts DNS queries over TLS on port 853. Testing requires tools that support TLS connections.

ⓘ

DoT requires TLS to be configured. See TLS Configuration if you haven’t set that up yet.

kdig (knot-dns)

kdig is part of the knot-dnsutils package and has native TLS support. It’s the best tool for testing DoT.

# Install on Debian/Ubuntu
sudo apt install knot-dnsutils

# Install on macOS
brew install knot

# Install on Arch
sudo pacman -S knot

Query via DoT

# Basic DoT query (trusted certificate)
kdig @dns.example.com +tls example.com

# DoT with explicit port
kdig @dns.example.com -p 853 +tls example.com

# DoT to a specific IP (bypass DNS for the server itself)
kdig @SERVER_IP +tls example.com

# DoT with self-signed cert (skip verification)
kdig @SERVER_IP +tls example.com +tls-ca=/path/to/ca.crt

Test per-group subdomain

# Query as the "kids" group via DoT
kdig @kids.dns.example.com +tls example.com

openssl s_client (manual)

You can verify that the TLS handshake works using openssl, even without sending a DNS query:

# Verify TLS handshake on port 853
openssl s_client -connect SERVER_IP:853 -servername dns.example.com

# Check certificate details
openssl s_client -connect SERVER_IP:853 -servername dns.example.com 2>/dev/null | \
  openssl x509 -noout -subject -issuer -dates

dog

dog is a modern DNS client with DoT support:

# Install
brew install dog          # macOS
cargo install dog         # Rust/any platform

# DoT query
dog example.com @tls:dns.example.com

DNS-over-HTTPS (DoH)

DoH sends DNS queries as HTTPS requests. You can test with any HTTP client.

curl

The most versatile testing tool for DoH. Works on every platform.

Wireformat (RFC 8484)

This is the standard DoH format used by browsers and operating systems:

# Query using DNS wireformat (POST)
echo -n 'q80BAAABAAAAAAAABmdvb2dsZQNjb20AAAEAAQ==' | \
  base64 -d | \
  curl -s -H 'Content-Type: application/dns-message' \
    --data-binary @- \
    'https://dns.example.com/dns-query' | \
  xxd

✓

The base64 string above encodes a DNS query for google.com type A. For ad-hoc testing, the JSON API method below is much easier to use.

JSON API (Google-style)

Blockasaurus also supports the Google-compatible JSON DNS API, which is much easier for manual testing:

# Basic DoH query (JSON format)
curl -s 'https://dns.example.com/dns-query?name=example.com&type=A' \
  -H 'Accept: application/dns-json' | python3 -m json.tool

# Verify blocking
curl -s 'https://dns.example.com/dns-query?name=ads.doubleclick.net&type=A' \
  -H 'Accept: application/dns-json' | python3 -m json.tool

# Query a specific client group via path
curl -s 'https://dns.example.com/kids?name=youtube.com&type=A' \
  -H 'Accept: application/dns-json' | python3 -m json.tool

# Query via subdomain
curl -s 'https://kids.dns.example.com/dns-query?name=youtube.com&type=A' \
  -H 'Accept: application/dns-json' | python3 -m json.tool

Self-signed certificate

# Skip TLS verification (for self-signed certs)
curl -sk 'https://SERVER_IP/dns-query?name=example.com&type=A' \
  -H 'Accept: application/dns-json'

# Or provide the CA certificate
curl -s --cacert /path/to/ca.crt \
  'https://dns.example.com/dns-query?name=example.com&type=A' \
  -H 'Accept: application/dns-json'

dog

# DoH query
dog example.com @https:dns.example.com/dns-query

Browser

Modern browsers can use DoH natively. To test that your browser is using blockasaurus:

Configure your browser to use your DoH server (https://dns.example.com/dns-query).
Visit a known-blocked domain (e.g., an ad-serving domain). It should fail to load.
Check the Live Logs tab in the blockasaurus web UI to see your queries appearing in real-time.

Verifying Blocking

A quick end-to-end test that blocking is working:

# This should resolve normally
dig @SERVER_IP example.com +short
# Expected: 93.184.216.34 (or similar)

# This should be blocked (returns 0.0.0.0 or NXDOMAIN)
dig @SERVER_IP ads.doubleclick.net +short
# Expected: 0.0.0.0 (if using Zero IP block type)

# Check a custom DNS entry
dig @SERVER_IP nas.home +short
# Expected: your configured IP

Using the Live Logs

The Live Logs tab in the web UI shows DNS queries in real-time via WebSocket. It’s the best way to see exactly what blockasaurus is doing:

Every query shows the domain, query type (A, AAAA, etc.), and response reason
Blocked queries are highlighted with an error indicator
Response duration (in ms) helps diagnose latency issues
The log streams automatically — no need to refresh

Troubleshooting

Common Issues

Symptom	Likely Cause	Fix
Connection refused on port 53	Blockasaurus not running or port conflict	Check `systemctl status blockasaurus`; check if another DNS server is on port 53
Queries resolve but nothing is blocked	No blocklists assigned to the client’s group	Check Blocklists → assign to client group → Apply
DoT/DoH not working	TLS not configured or cert issues	Check TLS Configuration; test with `openssl s_client`
Device not in expected client group	IP mismatch or identification method issue	Check Live Logs for the client’s actual IP; verify group membership
Slow DNS responses	Upstream timeout or unreachable upstream	Check upstream settings; try reducing timeout; check upstream health
“Apply” fails	Upstream probe failure (fail-on-error init strategy)	Verify upstreams are reachable, or switch to “blocking” init strategy

Quick Test Script

A one-liner to quickly verify all three DNS protocols against your server:

#!/bin/bash
# Quick blockasaurus test
SERVER=SERVER_IP
DOMAIN=dns.example.com

echo "=== Plain DNS ==="
dig @$SERVER example.com +short

echo "=== DoT (kdig) ==="
kdig @$DOMAIN +tls example.com +short

echo "=== DoH (curl) ==="
curl -s "https://$DOMAIN/dns-query?name=example.com&type=A" \
  -H 'Accept: application/dns-json' | python3 -m json.tool

echo "=== Blocking test ==="
RESULT=$(dig @$SERVER ads.doubleclick.net +short)
if [ "$RESULT" = "0.0.0.0" ] || [ -z "$RESULT" ]; then
  echo "Blocking: OK (ads.doubleclick.net blocked)"
else
  echo "Blocking: FAIL (got $RESULT)"
fi