Skip to main content

CLI Guide

dns-tester-go provides three command-line tools for different use cases.

dnstestergo query - DNS Query Tool​

Perform DNS lookups with multi-protocol support (UDP, TCP, DoT, DoH, DoQ).

Usage​

dnstestergo query <domain> [dns_servers...] [flags]

Flags​

FlagTypeDefaultDescription
-u, --api-urlstringhttp://localhost:5000API base URL
-t, --qtypestringAQuery type (A, AAAA, MX, TXT, PTR, etc.)
-i, --insecureboolfalseSkip TLS certificate verification
-d, --debugboolfalseShow detailed error messages
-p, --prettyboolfalseEnable emoji-enhanced output
-w, --warn-thresholdfloat1.0Response time warning threshold (seconds)
-c, --configstring-Path to config file

Examples​

Basic queries:

# UDP query
dnstestergo query example.com udp://8.8.8.8:53

# Multiple protocols
dnstestergo query cloudflare.com \
  udp://1.1.1.1:53 \
  tls://one.one.one.one:853 \
  https://cloudflare-dns.com/dns-query

# IPv6 lookup
dnstestergo query google.com udp://8.8.8.8:53 -t AAAA

# DNS-over-QUIC
dnstestergo query example.com quic://dns.adguard-dns.com:853

Advanced usage:

# With config file (uses servers from config)
dnstestergo query example.com -c conf/config.yaml

# Debug mode
dnstestergo query example.com udp://8.8.8.8:53 -d

# Pretty output with emojis
dnstestergo query github.com udp://9.9.9.9:53 -p

# Custom response time threshold
dnstestergo query example.com udp://slow.dns:53 -w 0.05

# Different query types
dnstestergo query example.com udp://8.8.8.8:53 -t MX   # Mail servers
dnstestergo query example.com udp://8.8.8.8:53 -t TXT  # TXT records
dnstestergo query example.com udp://8.8.8.8:53 -t NS   # Nameservers

Protocol Formats​

ProtocolFormatExample
UDPudp://<ip>:<port>udp://8.8.8.8:53
TCPtcp://<ip>:<port>tcp://1.1.1.1:53
DoTtls://<host>:<port>tls://dns.google:853
DoHhttps://<host><path>https://dns.google/dns-query
DoQquic://<host>:<port>quic://dns.adguard-dns.com:853

Output Format​

StatusFormat
Success✅ <server> - <protocol> - <time>ms - TTL: <ttl>s - <answers>
Warning⚠️ <server> - <protocol> - <time>ms (slow or NXDOMAIN)
Error❌ <server> - connection issue

dnstestergo server - API Server​

Start the DNS-Tester API server with optional in-memory or distributed workers.

Usage​

dnstestergo server [flags]

Flags​

FlagTypeDefaultDescription
-c, --configstring-Path to config file
-H, --hoststring0.0.0.0Server bind address
-P, --portstring5000Server port
-r, --redisstring-Redis URL (enables distributed workers)
-w, --workersintconfig/4Max number of in-memory workers
--dns-timeoutintconfig/5DNS query timeout in seconds
--max-serversintconfig/50Max DNS servers per request
--max-concurrentintconfig/500Max concurrent DNS queries
--max-retriesintconfig/3Number of retries per query
--rate-limit-rpsintconfig/10Requests per second (0 = disable)
--rate-limit-burstintconfig/20Rate limit burst size
--read-timeoutintconfig/15HTTP read timeout in seconds
--write-timeoutintconfig/15HTTP write timeout in seconds
--idle-timeoutintconfig/60HTTP idle timeout in seconds

Examples​

# Start with default settings (in-memory workers)
dnstestergo server

# Start with custom host/port
dnstestergo server --host 0.0.0.0 --port 8080

# Start with Redis backend (distributed workers)
dnstestergo server --redis redis://localhost:6379/0

# Start with custom config
dnstestergo server --config /path/to/config.yaml

# Override DNS settings
dnstestergo server --dns-timeout 10 --max-retries 5

# Disable rate limiting
dnstestergo server --rate-limit-rps 0

# Allow 200 servers per request
dnstestergo server --max-servers 200

# Combine config file with CLI overrides
dnstestergo server --config prod.yaml --port 8080 --max-servers 100

# Docker
docker run -p 5000:5000 sudo-tiz/dnstestergo:latest server

Environment Variables​

VariableDefaultDescription
DNS_TESTER_HOST0.0.0.0API bind address
DNS_TESTER_PORT5000API port
MAX_WORKERS4Worker concurrency (in-memory mode)
REDIS_URL-Redis connection URL
RATE_LIMIT_IP_SOURCERemoteAddrIP source for rate limiting

Priority: CLI flags > Environment variables > Config file > Defaults

dnstestergo worker - Standalone Worker​

Start a standalone worker that processes tasks from Redis queue.

Usage​

dnstestergo worker [flags]

Flags​

FlagTypeDefaultDescription
-r, --redisstringrequiredRedis URL (e.g., redis://localhost:6379/0)
-n, --concurrencyint4Number of concurrent workers
-c, --configstring-Path to config file
-M, --enable-metricsboolfalseEnable Prometheus metrics endpoint
-m, --metrics-portint9091Metrics port (if enabled)
--dns-timeoutintconfig/5DNS query timeout in seconds
--max-concurrentintconfig/500Max concurrent DNS queries
--max-retriesintconfig/3Number of retries per query

Examples​

# Start worker with default concurrency
dnstestergo worker --redis redis://localhost:6379/0

# Start worker with custom concurrency
dnstestergo worker --redis redis://localhost:6379/0 --concurrency 8

# Start worker with metrics (useful for single worker)
dnstestergo worker \
  --redis redis://localhost:6379/0 \
  --enable-metrics \
  --metrics-port 9091

# Start worker with custom config
dnstestergo worker \
  --config /path/to/config.yaml \
  --redis redis://localhost:6379/0

# Override DNS settings
dnstestergo worker \
  --redis redis://localhost:6379/0 \
  --dns-timeout 10 \
  --max-retries 5 \
  --max-concurrent 1000

# Combine config file with CLI overrides
dnstestergo worker \
  --config prod.yaml \
  --redis redis://localhost:6379/0 \
  --concurrency 16 \
  --dns-timeout 15

# Docker
docker run sudo-tiz/dnstestergo:latest worker \
  --redis redis://host.docker.internal:6379/0

Notes​

  • Redis is required for standalone workers
  • Use --enable-metrics carefully to avoid port conflicts when running multiple workers
  • Workers automatically register with Redis and process tasks from the queue
  • CLI flags override config file settings
  • See Configuration for DNS server settings

Docker Usage​

Query Tool​

docker run --rm sudo-tiz/dnstestergo:latest \
  query example.com udp://8.8.8.8:53

Server + Workers (docker-compose)​

docker compose up -d

With Custom Config​

docker run --rm \
  -v $(pwd)/conf:/conf \
  sudo-tiz/dnstestergo:latest \
  query example.com -c /conf/config.yaml

Troubleshooting​

IssueSolution
Invalid server formatUse protocol://host:port format
Connection refusedEnsure API server is running: docker compose up -d
Task failedCheck worker logs: docker compose logs dnstestergo-worker
TLS certificate errorUse --insecure flag (testing only)
Redis connection errorVerify Redis URL and that Redis is running
Port already in useChange port with --port or DNS_TESTER_PORT

See Also​