Testing and Diagnostics

This page provides detailed information on how to test, verify, and troubleshoot your nx9-dns-server installation.

Included Diagnostic Tools

nx9-dns-server comes with several built-in diagnostic tools located in the tools/ directory:

dnscheck.sh

A comprehensive DNS check script that verifies all record types and DNSSEC functionality.

# Basic usage
./tools/dnscheck.sh

# Specify a custom DNS server
./tools/dnscheck.sh 192.168.1.10

# Specify a custom domain
./tools/dnscheck.sh 192.168.1.10 example.com

Sample output:

🔍 DNS Check Tool for nx9-dns-server 🔍

Testing A records...
✅ A record for example.com resolved to 203.0.113.10

Testing AAAA records...
✅ AAAA record for example.com resolved to 2001:db8::1

Testing MX records...
✅ MX record for example.com resolved to 10 mail.example.com.

Testing NS records...
✅ NS records for example.com include ns1.example.com., ns2.example.com.

Testing SOA record...
✅ SOA record for example.com is valid

Testing TXT records...
✅ TXT record for example.com contains "v=spf1 a mx ~all"

Testing DNSSEC...
✅ DNSKEY record found for example.com
✅ RRSIG validation successful
✅ DS record found for example.com

All tests passed! Your DNS server is functioning correctly.

dns_dump.sh

Dumps all DNS records for a given domain.

# Basic usage
./tools/dns_dump.sh example.com

# Specify a custom DNS server
./tools/dns_dump.sh example.com 192.168.1.10

# Save output to a file
./tools/dns_dump.sh example.com > dns_dump.txt

Sample output:

📋 DNS Record Dump for example.com 📋

A Records:
example.com.		3600	IN	A	203.0.113.10
www.example.com.	3600	IN	A	203.0.113.10

AAAA Records:
example.com.		3600	IN	AAAA	2001:db8::1

MX Records:
example.com.		3600	IN	MX	10 mail.example.com.

NS Records:
example.com.		3600	IN	NS	ns1.example.com.
example.com.		3600	IN	NS	ns2.example.com.

SOA Record:
example.com.		3600	IN	SOA	ns1.example.com. hostmaster.example.com. 2023040201 10800 3600 604800 86400

TXT Records:
example.com.		3600	IN	TXT	"v=spf1 a mx ~all"

DNSSEC Records:
example.com.		3600	IN	DNSKEY	257 3 8 AwEAAb...
example.com.		3600	IN	DS	12345 8 2 A1B2C3...

performance_test.sh

Benchmarks DNS server performance under various loads.

# Basic usage (default: 1000 queries)
./tools/performance_test.sh

# Specify number of queries
./tools/performance_test.sh 5000

# Specify custom DNS server and query count
./tools/performance_test.sh 192.168.1.10 10000

Sample output:

🚀 DNS Performance Test 🚀

Testing server: 192.168.1.10
Query count: 5000
Domain: example.com

Starting benchmark...

Test 1: A record queries
Queries per second: 3256.4 qps
Avg response time: 0.307 ms

Test 2: DNSSEC-enabled queries
Queries per second: 1845.2 qps
Avg response time: 0.542 ms

Test 3: Mixed record types
Queries per second: 2103.6 qps
Avg response time: 0.475 ms

Test 4: TCP queries
Queries per second: 1024.8 qps
Avg response time: 0.976 ms

Test complete! Server performed within expected parameters.

api_test.sh

Tests the API endpoints with sample requests (available when API service is enabled).

# Basic usage
./tools/api_test.sh

# Specify custom API endpoint
./tools/api_test.sh http://192.168.1.10:8081

# Specify custom API endpoint with authentication token
./tools/api_test.sh http://192.168.1.10:8081 "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Sample output:

🔌 API Test Tool 🔌

Testing API endpoint: http://192.168.1.10:8081
Authentication: Bearer eyJhbGc...

Testing GET /api/v1/zones...
✅ Success: Retrieved 2 zones

Testing GET /api/v1/zones/example.com...
✅ Success: Zone details retrieved

Testing GET /api/v1/zones/example.com/records...
✅ Success: Retrieved 8 records

Testing POST /api/v1/zones/example.com/records...
✅ Success: Created new record

Testing PUT /api/v1/zones/example.com/records/123...
✅ Success: Updated record

Testing DELETE /api/v1/zones/example.com/records/123...
✅ Success: Deleted record

All API tests passed!

Manual Testing with dig

You can use the dig command-line tool to manually test DNS responses:

Basic dig Usage

# Test A record
dig @192.168.1.10 example.com A

# Test AAAA record
dig @192.168.1.10 example.com AAAA

# Test MX record
dig @192.168.1.10 example.com MX

# Test all records
dig @192.168.1.10 example.com ANY

Testing DNSSEC

# Test DNSSEC keys
dig @192.168.1.10 example.com DNSKEY +dnssec

# Test DNSSEC signatures
dig @192.168.1.10 example.com A +dnssec

# Verify DNSSEC validation
dig @192.168.1.10 example.com +dnssec +multi

Testing TCP Fallback

# Force TCP connection
dig @192.168.1.10 example.com A +tcp

Server Logs

To view server logs:

# View systemd logs
sudo journalctl -u dns-server.service

# View log file (if LOG_FILE is configured)
sudo cat /var/log/nx9-dns-server/server.log

# Follow log file in real-time
sudo tail -f /var/log/nx9-dns-server/server.log

# View Docker container logs
docker logs nx9-dns

# Follow Docker container logs
docker logs -f nx9-dns

Debugging with Increased Verbosity

To enable more detailed logging for troubleshooting:

# For systemd service:
sudo systemctl stop dns-server.service
sudo systemctl set-environment LOG_LEVEL=debug
sudo systemctl start dns-server.service

# For Docker:
docker stop nx9-dns
docker run -d --name nx9-dns \
  -p 53:53/udp -p 53:53/tcp \
  -e LOG_LEVEL=debug \
  [other parameters...]
  nx9-dns-server:latest

Common Issues and Solutions

DNS Server Not Responding

1. Check if the server is running:

   systemctl status dns-server.service
   # or
   docker ps | grep nx9-dns
   

2. Verify the server is listening on the correct ports:

   sudo netstat -tulpn | grep dns_server
   

3. Check for binding issues:

   sudo lsof -i :53
   

4. Check for firewall rules:

   sudo iptables -L -n | grep 53
   

DNSSEC Validation Failures

1. Verify DNSSEC key file:

   cat /var/nx9-dns-server/processed.key
   

2. Check for key processing errors in logs:

   sudo grep "DNSSEC" /var/log/nx9-dns-server/server.log
   

3. Regenerate DNSSEC keys:

   dnssec-keygen -a RSASHA256 -b 2048 -n ZONE example.com
   

Database Issues

1. Check database permissions:

   ls -la /var/nx9-dns-server/dns.db
   

2. Verify database integrity:

   sqlite3 /var/nx9-dns-server/dns.db .schema
   

3. Check for database errors in logs:

   sudo grep "database" /var/log/nx9-dns-server/server.log
   

API or Web UI Connection Issues

1. Verify services are running:

   sudo netstat -tulpn | grep 8080
   sudo netstat -tulpn | grep 8081
   

2. Check for SSL certificate issues:

   openssl x509 -in /etc/ssl/certs/api.crt -text -noout
   

3. Test local connectivity:

   curl -v http://localhost:8081/api/v1/health
   

Performance Tuning

If you experience performance issues, consider these adjustments:

1. Increase worker threads:

   export WORKER_THREADS=16
   

2. Optimize database cache:

   export DB_CACHE_SIZE=50
   

3. Adjust network parameters:

   # Increase maximum UDP packet size
   export MAX_UDP_SIZE=8192
   
   # Increase TCP connection limits
   export MAX_TCP_CLIENTS=250
   

4. Enable query caching:

   export DNS_CACHE_TTL=7200
   

Health Checking

To set up automated health checks:

# Simple DNS health check
dig @192.168.1.10 example.com A +short | grep -q "^[0-9]" && echo "DNS OK" || echo "DNS FAILED"

# API health check
curl -s http://192.168.1.10:8081/api/v1/health | grep -q "ok" && echo "API OK" || echo "API FAILED"

# Web UI health check
curl -s http://192.168.1.10:8080/health | grep -q "ok" && echo "UI OK" || echo "UI FAILED"

Monitoring Integration

nx9-dns-server can be integrated with monitoring systems:

Prometheus

When METRICS_ENABLE=true is set, the server exposes metrics at the configured endpoint (default: http://127.0.0.1:9100/metrics).

Example Prometheus configuration:

scrape_configs:
  - job_name: 'nx9-dns-server'
    scrape_interval: 15s
    static_configs:
      - targets: ['192.168.1.10:9100']

Grafana Dashboard

A sample Grafana dashboard is available in the tools/grafana/ directory:

# Import dashboard
curl -X POST -H "Content-Type: application/json" -d @tools/grafana/nx9-dns-dashboard.json http://grafana-server:3000/api/dashboards/db

The dashboard includes panels for:

• Query rate and latency
• Record type distribution
• Error rates
• Cache hit ratio
• System resource usage