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.

```bash

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.

```bash

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.

```bash

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).

```bash

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

```bash

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

```bash

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

```bash

Force TCP connection

dig @192.168.1.10 example.com A +tcp ```

Server Logs

To view server logs:

```bash

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:

```bash

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: bash systemctl status dns-server.service # or docker ps | grep nx9-dns

  2. Verify the server is listening on the correct ports: bash sudo netstat -tulpn | grep dns_server

  3. Check for binding issues: bash sudo lsof -i :53

  4. Check for firewall rules: bash sudo iptables -L -n | grep 53

DNSSEC Validation Failures

  1. Verify DNSSEC key file: bash cat /var/nx9-dns-server/processed.key

  2. Check for key processing errors in logs: bash sudo grep "DNSSEC" /var/log/nx9-dns-server/server.log

  3. Regenerate DNSSEC keys: bash dnssec-keygen -a RSASHA256 -b 2048 -n ZONE example.com

Database Issues

  1. Check database permissions: bash ls -la /var/nx9-dns-server/dns.db

  2. Verify database integrity: bash sqlite3 /var/nx9-dns-server/dns.db .schema

  3. Check for database errors in logs: bash sudo grep "database" /var/log/nx9-dns-server/server.log

API or Web UI Connection Issues

  1. Verify services are running: bash sudo netstat -tulpn | grep 8080 sudo netstat -tulpn | grep 8081

  2. Check for SSL certificate issues: bash openssl x509 -in /etc/ssl/certs/api.crt -text -noout

  3. Test local connectivity: bash curl -v http://localhost:8081/api/v1/health

Performance Tuning

If you experience performance issues, consider these adjustments:

  1. Increase worker threads: bash export WORKER_THREADS=16

  2. Optimize database cache: bash export DB_CACHE_SIZE=50

  3. Adjust network parameters: ```bash # Increase maximum UDP packet size export MAX_UDP_SIZE=8192

# Increase TCP connection limits export MAX_TCP_CLIENTS=250 ```

  1. Enable query caching: bash export DNS_CACHE_TTL=7200

Health Checking

To set up automated health checks:

```bash

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: yaml 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: ```bash

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