Configuration Reference - thakares/nx9-dns-server GitHub Wiki

Configuration Reference

This page provides a complete reference for all configuration options available in the nx9-dns-server.

Environment Variables

Configuration of nx9-dns-server is primarily done through environment variables, making it flexible for different deployment scenarios including traditional server deployments, Docker containers, and orchestration platforms like Kubernetes.

Core DNS Settings

Variable Description Default Example
DNS_BIND IP address and port to bind DNS server 0.0.0.0:53 192.168.1.10:53
DNS_DB_PATH Path to SQLite database file dns.db /var/nx9-dns-server/dns.db
DNSSEC_KEY_FILE Path to DNSSEC key file (Required) /var/nx9-dns-server/Kexample.com.+008+24550.key
DNS_FORWARDERS Comma-separated list of upstream DNS resolvers (None) 8.8.8.8:53,1.1.1.1:53
DNS_NS_RECORDS Comma-separated list of NS records (Required) ns1.example.com.,ns2.example.com.
DNS_CACHE_TTL Cache TTL in seconds 3600 7200

Systemd Service Configuration

For traditional Linux deployments, a systemd service file is recommended. Create /etc/systemd/system/dns-server.service:

[Unit]
Description=NX9 DNS Server
After=network.target

[Service]
Type=simple
User=dnsuser
Group=dns
WorkingDirectory=/var/nx9-dns-server
ExecStart=/usr/local/bin/dns_server
Restart=on-failure
RestartSec=5s
Environment="DNS_BIND=0.0.0.0:53"
Environment="DNS_DB_PATH=/var/nx9-dns-server/dns.db"
Environment="DNSSEC_KEY_FILE=/var/nx9-dns-server/Kexample.com.+008+24550.key"
Environment="DNS_FORWARDERS=8.8.8.8:53,1.1.1.1:53"
Environment="DNS_NS_RECORDS=ns1.example.com.,ns2.example.com."
Environment="LOG_FILE=/var/log/nx9-dns-server/server.log"
Environment="AUTH_SECRET=your-secure-random-string-here"


[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable dns-server.service
sudo systemctl start dns-server.service

Docker Environment Configuration

When running with Docker, environment variables can be passed directly to the container:

docker run -d --name nx9-dns \
  -p 53:53/udp -p 53:53/tcp \
  -p 8080:8080 -p 8081:8081 \
  -v /path/to/dns.db:/var/nx9-dns-server/dns.db \
  -v /path/to/keys:/etc/nx9-dns-server/keys \
  -e DNS_BIND=0.0.0.0:53 \
  -e DNS_DB_PATH=/var/nx9-dns-server/dns.db \
  -e DNSSEC_KEY_FILE=/etc/nx9-dns-server/keys/Kexample.com.key \
  -e DNS_FORWARDERS=8.8.8.8:53,1.1.1.1:53 \
  -e DNS_NS_RECORDS=ns1.example.com.,ns2.example.com. \
  -e WEB_UI_BIND=0.0.0.0:8080 \
  -e API_BIND=0.0.0.0:8081 \
  -e AUTH_SECRET=your-secure-random-string-here \
  nx9-dns-server:latest

Configuration Best Practices

  1. Security:

    • Always bind web UI and API services to localhost (127.0.0.1) in production unless external access is required
    • Use strong, randomly generated values for AUTH_SECRET
    • Set up SSL certificates for web UI and API services

  2. Performance:

    • Adjust WORKER_THREADS based on available CPU cores
    • Tune DB_CACHE_SIZE based on database size and available memory
    • Consider increasing MAX_UDP_SIZE for DNSSEC responses

  3. Resilience:

    • Always configure multiple DNS forwarders for redundancy
    • Set up log rotation to prevent disk space issues
    • Use the systemd Restart=on-failure option or Docker's restart: unless-stopped policy
⚠️ **GitHub.com Fallback** ⚠️