Skip to main content
This guide helps diagnose and resolve common NSD operational issues using log analysis, debugging tools, and systematic troubleshooting approaches.

​
Log Files

NSD logs to the system log by default, or to a custom location if configured.

​
Log Configuration

server:
  # Log to file instead of syslog
  logfile: "/var/log/nsd.log"
  
  # Increase verbosity
  verbosity: 2
Verbosity levels:
  • 0 - Errors and warnings only (default)
  • 1 - Operational information
  • 2 - Debug information
  • 3 - Very verbose debug output

​
Viewing Logs

# System log (syslog/systemd)
sudo journalctl -u nsd -f

# Traditional syslog
sudo tail -f /var/log/syslog | grep nsd

# Custom log file
sudo tail -f /var/log/nsd.log
Increase verbosity temporarily for debugging, but return to level 0 or 1 in production to avoid performance impact and log file growth.

​
Common Log Messages

​
Reload Failures

Meaning: The reload process failed, and NSD continues using the previous zone data.Common causes:
  • Syntax errors in zone files
  • Missing zone files
  • File permission issues
  • Corrupted database
Diagnosis:
# Check zone file syntax
nsd-checkzone example.com /etc/nsd/example.com.zone

# Validate configuration
nsd-checkconf /etc/nsd/nsd.conf

# Check file permissions
ls -la /etc/nsd/*.zone
Solution:
  1. Fix syntax errors reported by nsd-checkzone
  2. Ensure zone files exist and are readable by the NSD user
  3. Verify database file isn’t corrupted
  4. Try reloading again: nsd-control reload

​
Database Corruption

Meaning: The IXFR database file contains incomplete data, and NSD is removing the corrupted portion.Impact: Zone transfer history may be lost, but NSD continues operating normally.Action required: Usually none - NSD automatically repairs the corruption. If this message appears frequently, investigate:
  • Disk space issues
  • Filesystem errors
  • Abrupt shutdowns (power loss, kill -9)
Prevention:
# Ensure clean shutdowns
nsd-control stop

# Check filesystem health
sudo fsck /dev/sdX

# Verify disk space
df -h

​
Memory Management

Meaning: NSD reports the size of its memory recycle bin after each reload.Background: NSD allocates and deallocates memory for IXFR updates. Deallocated memory is kept in a recycle bin for reuse.When to act: If the number grows very large (hundreds of megabytes):
# Restart NSD to reset the recycle bin
nsd-control stop
nsd
Normal behavior: Small to moderate values are expected during regular operation.

​
Zone Transfer Limits

Meaning: More than 32 zones need simultaneous zone transfers.Details:
  • NSD allows up to 32 concurrent TCP connections for zone transfers
  • This is a compile-time constant in xfrd-tcp.h
  • NSD reuses connections to the same primary (up to 64k zones per connection)
When this happens:
  • You have more than 32 different primary servers
  • Or more than 2 million zones needing simultaneous updates (32 × 64k)
Impact: Additional zones wait in a queue until connections become available.Solution: If this happens frequently:
  1. Stagger zone updates across different times
  2. Consolidate primaries to reduce connection count
  3. Contact NLnet Labs about making this a configurable option
  4. Consider modifying the source and recompiling (advanced)

​
NSEC3 Errors

Meaning: The zone uses NSEC3 with a hash algorithm not supported by this NSD version.Impact:
  • NSD cannot serve the NSEC3 chain with the unknown algorithm
  • If no supported NSEC/NSEC3 chains exist, DNSSEC authenticated denials will fail
Solutions:
  1. Upgrade NSD to a version supporting the hash algorithm
  2. Re-sign the zone with a supported algorithm (typically SHA-1)
  3. Check primary configuration if this is a secondary zone
Verification:
# Check NSEC3PARAM records
dig NSEC3PARAM example.com @localhost

# Verify NSD version
nsd -v

​
Startup Issues

​
Port Already in Use

Symptom: 
error: can't bind socket: Address already in use
Diagnosis: 
# Check what's using port 53
sudo lsof -i :53
sudo netstat -tulnp | grep :53

# Check for running NSD instances
ps aux | grep nsd
Common causes:
  • Another NSD instance is running
  • systemd-resolved is using port 53
  • BIND or another DNS server is running
  • Stale PID file after crash
Solutions: 
# Disable systemd-resolved DNS stub listener
sudo systemctl stop systemd-resolved
sudo systemctl disable systemd-resolved

# Or configure it to not bind to port 53
sudo mkdir -p /etc/systemd/resolved.conf.d
echo -e "[Resolve]\nDNSStubListener=no" | sudo tee /etc/systemd/resolved.conf.d/nsd.conf
sudo systemctl restart systemd-resolved

# Check if process exists
cat /var/run/nsd.pid
ps -p <pid>

# If process doesn't exist, remove stale PID file
sudo rm /var/run/nsd.pid

# Start NSD
sudo systemctl start nsd

​
Permission Denied

Symptom: 
error: can't bind socket: Permission denied
Cause: Insufficient privileges to bind to port 53 (< 1024). Solutions: 
# Allow NSD to bind privileged ports without running as root
sudo setcap CAP_NET_BIND_SERVICE=+ep /usr/sbin/nsd

# Verify
getcap /usr/sbin/nsd

server:
  username: nsd  # Drop to this user after binding
Start NSD as root (via systemd or init), and it will drop privileges after binding to port 53.

​
Zone Transfer Problems

​
Transfers Not Working

Diagnosis checklist: 
# 1. Check zone configuration
nsd-checkconf /etc/nsd/nsd.conf

# 2. Verify network connectivity
ping <primary-ip>
telnet <primary-ip> 53

# 3. Test zone transfer manually
dig @<primary-ip> example.com AXFR

# 4. Check ACLs on primary server
# Ensure your secondary IP is in provide-xfr list

# 5. Verify TSIG keys match
# Compare key name, algorithm, and secret

# 6. Check logs on both servers
sudo journalctl -u nsd -f
Error: Zone transfer fails with TSIG error.Diagnosis:
# Test transfer with verbose output
dig @<primary-ip> example.com AXFR -y hmac-sha256:keyname:secret
Common issues:
  • Key names don’t match exactly (case-sensitive)
  • Different algorithms configured on primary vs secondary
  • Secret is different or improperly encoded
  • Clock skew between servers (TSIG uses timestamps)
Solutions:
# Verify time synchronization
ntpq -p
timedatectl status

# Check key configuration on both servers
nsd-checkconf /etc/nsd/nsd.conf
Diagnosis:
# Check firewall rules
sudo iptables -L -n -v | grep 53
sudo firewall-cmd --list-all

# Test TCP connectivity (zone transfers use TCP)
nc -v <primary-ip> 53
telnet <primary-ip> 53

# Check primary is listening
# On primary server:
sudo netstat -tulnp | grep :53
Solutions:
  • Open TCP port 53 in firewall
  • Verify primary server is running
  • Check network ACLs and security groups
  • Ensure no NAT issues between servers

​
Configuration Errors

​
Validation Tools

# Check configuration file syntax
nsd-checkconf /etc/nsd/nsd.conf

# Validate specific zone file
nsd-checkzone example.com /etc/nsd/example.com.zone

# Verbose output for debugging
nsd-checkconf -v /etc/nsd/nsd.conf
Common errors:
  • Missing quotes around values with spaces
  • Incorrect indentation
  • Typos in option names
  • Invalid IP addresses or CIDR notation
  • Mismatched TSIG key names

​
Performance Issues

​
High CPU Usage

Diagnosis: 
# Check query rate
nsd-control stats | grep num.queries

# Monitor CPU per process
top -p $(pgrep nsd | tr '\n' ',')

# Check server processes
ps aux | grep nsd
Solutions:
Scale server processes to match CPU cores:
server:
  server-count: 4  # Match your CPU core count
  reuseport: yes
See Performance Tuning for details.
server:
  rrl-size: 1000000
  rrl-ratelimit: 200
  rrl-whitelist-ratelimit: 2000
Protects against amplification attacks and excessive query load.

​
Memory Issues

Check memory usage: 
# Per-process memory
ps aux | grep nsd

# Detailed memory info
nsd-control stats | grep mem

# System memory
free -h
If memory usage is excessive: 
# Restart to clear recycle bin
nsd-control stop
nsd

# Check for very large zones
du -sh /etc/nsd/*.zone | sort -h

​
Debugging Techniques

​
Query Testing

# Test basic query
dig @localhost example.com SOA

# Test zone transfer
dig @localhost example.com AXFR

# Test DNSSEC
dig @localhost example.com DNSKEY +dnssec

# Verbose output
dig @localhost example.com ANY +trace +dnssec

​
Using nsd-control

# View status
nsd-control status

# Display statistics
nsd-control stats
nsd-control stats_noreset  # Don't reset counters

# Force zone transfer
nsd-control transfer example.com
nsd-control force_transfer example.com

# Send notifications
nsd-control notify example.com

# Write zone files to disk
nsd-control write

# Reload configuration and zones
nsd-control reconfig
nsd-control reload

​
Packet Capture

Capture DNS traffic for deep analysis: 
# Capture all DNS traffic
sudo tcpdump -i any -n port 53 -w /tmp/dns-capture.pcap

# Capture specific zone transfer
sudo tcpdump -i any -n "tcp port 53 and host <primary-ip>" -w /tmp/axfr.pcap

# Real-time monitoring
sudo tcpdump -i any -n port 53 -l
Analyze with Wireshark: 
wireshark /tmp/dns-capture.pcap

​
Logging Tools

NSD doesn’t log queries by default, but you can use external tools:
If compiled with DNSTAP:
dnstap:
  dnstap-enable: yes
  dnstap-socket-path: "/var/run/nsd-dnstap.sock"
  dnstap-send-identity: yes
  dnstap-send-version: yes
  dnstap-log-auth-query-messages: yes
  dnstap-log-auth-response-messages: yes
Analyze DNSTAP output with dnstap-read.
# Log queries in real-time
sudo tcpdump -i any -n -l port 53 | tee /var/log/dns-queries.log

# Decode DNS packets
sudo tcpdump -i any -n -vv port 53
Use CAIDA’s dnsstat tool:
# Install dnsstat
# https://www.caida.org/catalog/software/dnsstat/

# Capture statistics
sudo dnsstat -i eth0 -o /var/log/dnsstat.log

​
Getting Help

​
Information to Collect

Before reporting issues: 
# NSD version and compile options
nsd -v

# Configuration check
nsd-checkconf /etc/nsd/nsd.conf

# Recent log entries
sudo journalctl -u nsd -n 100 --no-pager

# System information
uname -a
lsb_release -a

# Statistics
nsd-control stats_noreset

​
Support Resources

When reporting issues:
  1. Include NSD version and OS details
  2. Provide relevant configuration sections (redact secrets)
  3. Include complete error messages and log entries
  4. Describe steps to reproduce the problem
  5. Mention any recent changes to configuration or system

​
Quick Reference

​
Essential Commands

# Configuration validation
nsd-checkconf /etc/nsd/nsd.conf
nsd-checkzone example.com /etc/nsd/example.com.zone

# Service management
sudo systemctl start nsd
sudo systemctl stop nsd
sudo systemctl restart nsd
sudo systemctl status nsd

# Control commands
nsd-control status
nsd-control reload
nsd-control reconfig
nsd-control stats

# Testing
dig @localhost example.com SOA
dig @localhost example.com AXFR

# Monitoring
sudo journalctl -u nsd -f
tail -f /var/log/nsd.log

Build docs developers (and LLMs) love

Get started for freeTalk to us