Troubleshooting Guide

Common issues and solutions for NexoralDNS installation, configuration, and operation.

Quick Diagnostics

Before diving into specific issues, run these diagnostic commands:

Check Service Status

sudo docker compose ps

View All Logs

sudo docker compose logs -f

View Specific Service Logs

sudo docker compose logs -f dns-server

Check Version

cat VERSION

Installation Issues

Problem: Installation Script Fails

Symptoms:

• Installation script exits with error
• "Permission denied" messages
• Docker-related errors

Solutions:

1. Ensure you have sudo privileges:

sudo -v

2. Check if Docker is installed:

docker --version

3. Manually install Docker if needed:

# Update package index
sudo apt update

# Install prerequisites
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Set up stable repository
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

4. Re-run the installation:

curl -fsSL https://raw.githubusercontent.com/nexoral/NexoralDNS/main/Scripts/install.sh | bash -

Problem: Port Conflicts

Symptoms:

• "Port 53 already in use"
• "Port 4000 already in use"

Solutions:

1. Check what's using port 53:

sudo netstat -tulpn | grep :53

2. Common culprits and how to disable them:

systemd-resolved (Ubuntu/Debian):

# Disable systemd-resolved
sudo systemctl disable systemd-resolved
sudo systemctl stop systemd-resolved

# Remove symlink
sudo rm /etc/resolv.conf

# Create new resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

dnsmasq:

sudo systemctl disable dnsmasq
sudo systemctl stop dnsmasq

3. Check port 4000:

sudo netstat -tulpn | grep :4000

DNS Resolution Issues

Problem: DNS Not Working After Installation

Symptoms:

• Websites not loading
• DNS queries timing out
• Custom domains not resolving

Solutions:

1. Verify NexoralDNS is running:

sudo docker compose ps

All services should show status "Up".

2. Test DNS resolution directly:

# On Linux/Mac
dig @localhost google.com

# On Windows
nslookup google.com localhost

3. Check if port 53 is listening:

sudo netstat -tulpn | grep :53

4. Verify router DNS settings:

• Log into your router's admin panel
• Navigate to DHCP/DNS settings
• Ensure Primary DNS is set to your NexoralDNS machine's IP
• Restart your router if settings were changed

5. Check firewall:

# Allow DNS traffic
sudo ufw allow 53/udp
sudo ufw allow 53/tcp

# Allow web dashboard
sudo ufw allow 4000/tcp

Problem: Custom Domains Not Resolving

Symptoms:

• External domains work, but custom domains return NXDOMAIN
• Custom domains work from server but not from other devices

Solutions:

1. Verify the domain exists in the database:

• Open dashboard at http://localhost:4000
• Navigate to DNS Records
• Confirm your custom domain is listed and enabled

2. Clear cache:

# Redis cache clear
docker exec -it nexoraldns-redis-1 redis-cli FLUSHDB

3. Check service status:

• In dashboard, verify service is "Active"
• Navigate to Settings → Service Status

4. Test from the server:

dig @localhost myapp.local

5. Test from another device:

dig @192.168.1.100 myapp.local

(Replace 192.168.1.100 with your server's IP)

Web Dashboard Issues

Problem: Cannot Access Web Dashboard

Symptoms:

• "Connection refused" when accessing localhost:4000
• Dashboard not loading

Solutions:

1. Check if web service is running:

sudo docker compose ps | grep web

2. Restart the web service:

sudo docker compose restart web

3. Check logs for errors:

sudo docker compose logs web

4. Verify port 4000 is accessible:

curl http://localhost:4000

5. Check from another device (replace with your server IP):

curl http://192.168.1.100:4000

Problem: Login Issues

Symptoms:

• "Invalid credentials" error
• Forgot password

Solutions:

1. Verify you're using default credentials (first login):

• Username: admin
• Password: admin

2. Reset admin password (if forgotten):

# Access MongoDB container
docker exec -it nexoraldns-mongodb-1 mongosh

# Use the database
use nexoraldns

# Reset password (hash for 'admin')
db.users.updateOne(
  { username: "admin" },
  { $set: { password: "$2b$10$abcdefghijklmnopqrstuvwxyz" } }
)

exit

Performance Issues

Problem: Slow DNS Resolution

Symptoms:

• DNS queries taking longer than expected
• Websites loading slowly

Solutions:

1. Check Redis cache status:

docker exec -it nexoraldns-redis-1 redis-cli INFO stats

2. Verify cache hit rate in dashboard:

• Navigate to Analytics → Performance
• Cache hit rate should be >80%

3. Check system resources:

docker stats

4. Restart services to clear issues:

sudo docker compose restart

5. Check upstream DNS connectivity:

dig @8.8.8.8 google.com

Update Issues

Problem: Update Fails

Symptoms:

• Update command fails
• Cannot pull new images
• Network errors during update

Solutions:

1. Check internet connectivity:

ping -c 4 8.8.8.8

2. If update fails, remove and reinstall:

# Remove existing installation
curl -fsSL https://raw.githubusercontent.com/nexoral/NexoralDNS/main/Scripts/install.sh | sudo bash -s remove

# Fresh installation
curl -fsSL https://raw.githubusercontent.com/nexoral/NexoralDNS/main/Scripts/install.sh | bash -

3. If network requests are blocked, restore system DNS:

sudo systemctl enable systemd-resolved
sudo systemctl restart systemd-resolved

4. Manual resolv.conf fix:

sudo nano /etc/resolv.conf
# Set or ensure the file contains:
nameserver 127.0.0.53

Database Issues

Problem: MongoDB Connection Errors

Solutions:

1. Check MongoDB is running:

sudo docker compose ps | grep mongo

2. View MongoDB logs:

sudo docker compose logs mongodb

3. Restart MongoDB:

sudo docker compose restart mongodb

Problem: Redis Connection Errors

Solutions:

1. Check Redis is running:

sudo docker compose ps | grep redis

2. Test Redis connection:

docker exec -it nexoraldns-redis-1 redis-cli PING

Should return: PONG

3. Restart Redis:

sudo docker compose restart redis

Complete Uninstallation

If you need to completely remove NexoralDNS from your system:

curl -fsSL https://raw.githubusercontent.com/nexoral/NexoralDNS/main/Scripts/install.sh | sudo bash -s remove

This will:

• Stop all NexoralDNS services
• Remove Docker containers and images
• Delete all configuration files and data
• Clean up the installation directory

Still Need Help?

If your issue isn't covered here:

1. Check GitHub Issues: Search for similar problems at github.com/nexoral/NexoralDNS/issues
2. Open a New Issue: Provide detailed information about your problem
3. Include Logs: Always include relevant log output
4. System Information: Include OS version, Docker version, and NexoralDNS version
5. Premium Support: Premium users can contact priority support for faster assistance

Useful Commands Reference

Common Error Messages