Technitium DNS Server Documentation

Server IP: 10.3.3.3 Hostname: ha.local.dev Web Console: http://10.3.3.3:5380/ Last Updated: November 20, 2025

Overview

The Technitium DNS Server is a Docker-based DNS server running on the local development infrastructure. It provides DNS resolution and management for the local.dev domain and related services.

What We Have

DNS Server Software: Technitium DNS Server
Version: Latest (Image created: November 16, 2025)
Deployment Method: Docker container
Container Name: dns-server
Container ID: ac77dbea6dd2
Image: technitium/dns-server:latest
Image ID: 661b3e38234c

Where It Runs

Server Details

Host: ha.local.dev (10.3.3.3)
Platform: Docker on Linux
Container Runtime: Docker (overlay2 storage driver)

Container Configuration

Container Name: dns-server

Port Mappings:

53/tcp → Host port 53 (DNS over TCP)
53/udp → Host port 53 (DNS over UDP)
5380/tcp → Host port 5380 (Web Console)

Exposed Ports (not mapped to host):

80/tcp - HTTP
443/tcp, 443/udp - HTTPS/DNS over HTTPS
67/udp - DHCP (optional)
853/tcp, 853/udp - DNS over TLS
8053/tcp - Alternative DNS port
53443/tcp - DNS over QUIC

Volume Mounts:

Volume Name: technitium-dns_config
Host Path: /var/lib/docker/volumes/technitium-dns_config/_data
Container Path: /etc/dns
Purpose: Persistent storage for DNS configuration, zones, logs, and cache

Restart Policy: unless-stopped (automatically restarts unless manually stopped)

Network: Bridge mode (172.17.0.2 on Docker bridge network)

DNS Zones

The DNS server manages the following zones:

do.dev.zone - Development domain zone
local.dev.zone - Local development domain
sell.dev.zone - Additional development domain
3.3.3.10.in-addr.arpa.zone - Reverse DNS for 10.3.3.0/24 network
ntp.org.zone - NTP organization zone

Zone files are stored in: /var/lib/docker/volumes/technitium-dns_config/_data/zones/

Data Locations

All DNS server data is stored in the Docker volume technitium-dns_config:

/var/lib/docker/volumes/technitium-dns_config/_data/
├── apps/              # DNS server apps/plugins
├── auth.config        # Authentication configuration
├── blocklists/        # DNS blocklists
├── cache.bin          # DNS cache
├── dns.config         # Main DNS configuration (binary)
├── log.config         # Logging configuration
├── logs/              # Server logs
├── scopes/            # DNS scopes
├── stats/             # Statistics data
└── zones/             # DNS zone files

Access and Management

Web Console

URL: http://10.3.3.3:5380/
Default Credentials: Set during initial setup (check documentation or authentication config)
Features:
- DNS zone management
- Query logs
- Statistics and analytics
- Server settings
- Block lists management

SSH Access

ssh root@10.3.3.3

Docker Commands

View container status:

docker ps | grep dns-server

View container logs:

docker logs dns-server
docker logs -f dns-server  # Follow logs in real-time

Stop the DNS server:

docker stop dns-server

Start the DNS server:

docker start dns-server

Restart the DNS server:

docker restart dns-server

How to Update

Method 1: Standard Update (Recommended)

Step 1: Pull the latest image

ssh root@10.3.3.3 'docker pull technitium/dns-server:latest'

Step 2: Stop and remove the old container

ssh root@10.3.3.3 'docker stop dns-server && docker rm dns-server'

Step 3: Recreate the container with the new image

ssh root@10.3.3.3 'docker run -d --name dns-server \
  -p 53:53/udp -p 53:53/tcp \
  -p 5380:5380/tcp \
  --volume technitium-dns_config:/etc/dns \
  --restart unless-stopped \
  technitium/dns-server:latest'

Step 4: Verify the update

ssh root@10.3.3.3 'docker ps | grep dns-server'

Step 5: Check the web console

Navigate to http://10.3.3.3:5380/
Verify DNS server is accessible and functioning

Method 2: Quick Update Script

Create a script file update-dns-server.sh:

#!/bin/bash
set -e

echo "=== Technitium DNS Server Update ==="
echo "Pulling latest image..."
docker pull technitium/dns-server:latest

echo "Stopping current container..."
docker stop dns-server

echo "Removing old container..."
docker rm dns-server

echo "Creating new container with updated image..."
docker run -d --name dns-server \
  -p 53:53/udp -p 53:53/tcp \
  -p 5380:5380/tcp \
  --volume technitium-dns_config:/etc/dns \
  --restart unless-stopped \
  technitium/dns-server:latest

echo "Waiting for DNS server to start..."
sleep 3

echo "Verifying container status..."
docker ps | grep dns-server

echo "=== Update Complete ==="
echo "Web console: http://10.3.3.3:5380/"

Run it on the server:

ssh root@10.3.3.3 'bash -s' < update-dns-server.sh

⚠️ DO NOT use the systemd installer script - The DNS server is Docker-based, not systemd-based. Running the installer script from https://blog.technitium.com/2017/11/running-dns-server-on-ubuntu-linux.html will create conflicts.

✅ Configuration is preserved - The Docker volume technitium-dns_config persists all configuration, zones, and data across updates.

✅ Zero downtime updates - DNS queries may be briefly unavailable (1-2 seconds) during container recreation.

Backup and Restore

Backup

Option 1: Volume Backup

ssh root@10.3.3.3 'docker run --rm \
  -v technitium-dns_config:/source \
  -v /root/backups:/backup \
  alpine tar czf /backup/technitium-dns-backup-$(date +%Y%m%d).tar.gz -C /source .'

Option 2: Web Console Export

Navigate to Settings → Backup in the web console
Download backup file

Restore

From Volume Backup:

# Stop the DNS server
ssh root@10.3.3.3 'docker stop dns-server'

# Restore the backup
ssh root@10.3.3.3 'docker run --rm \
  -v technitium-dns_config:/target \
  -v /root/backups:/backup \
  alpine sh -c "cd /target && tar xzf /backup/technitium-dns-backup-YYYYMMDD.tar.gz"'

# Start the DNS server
ssh root@10.3.3.3 'docker start dns-server'

From Web Console Backup:

Navigate to Settings → Restore in the web console
Upload backup file

Troubleshooting

DNS Server Not Responding

Check if container is running:

ssh root@10.3.3.3 'docker ps | grep dns-server'

Check container logs:

ssh root@10.3.3.3 'docker logs --tail 100 dns-server'

Restart the container:

ssh root@10.3.3.3 'docker restart dns-server'

Web Console Not Accessible

Verify port 5380 is listening:

ssh root@10.3.3.3 'netstat -tlnp | grep 5380'

Check firewall rules (if applicable):

ssh root@10.3.3.3 'iptables -L -n | grep 5380'

Port Conflicts

If you encounter port 53 or 5380 conflicts:

Check what's using the ports:

ssh root@10.3.3.3 'lsof -i :53'
ssh root@10.3.3.3 'lsof -i :5380'

Common conflicts:

Port 53: systemd-resolved, dnsmasq, or other DNS services
Port 5380: Another Technitium instance or web service

Container Won't Start

Check Docker daemon status:

ssh root@10.3.3.3 'systemctl status docker'

Check disk space:

ssh root@10.3.3.3 'df -h'

Check Docker logs:

ssh root@10.3.3.3 'journalctl -u docker -n 100'

Monitoring

Container Health

Check container status:

docker ps -a | grep dns-server

Check resource usage:

docker stats dns-server --no-stream

DNS Performance

Test DNS resolution:

dig @10.3.3.3 local.dev
nslookup local.dev 10.3.3.3

Check query logs in web console:

Navigate to Dashboard → Query Logs

Security Considerations

Web Console Access: The web console on port 5380 should be restricted to the local network only
Authentication: Ensure strong passwords are set for web console access
Firewall Rules: Configure firewall to allow DNS queries (port 53) from trusted networks only
Updates: Regularly update the Docker image to get security patches
Backup: Maintain regular backups of the DNS configuration

Integration with Local Development

The DNS server is integrated with the local development infrastructure:

Local.dev domain: Manages DNS records for *.local.dev
Development domains: Handles do.dev, sell.dev subdomains
Reverse DNS: Provides reverse DNS for the 10.3.3.0/24 network
Traefik Integration: Works with Traefik reverse proxy for local service routing

For more information on DNS design and integration, see:

DNS_DESIGN.md - DNS architecture and design
TRAEFIK_MIGRATION_GUIDE.md - Traefik integration

References

Official Documentation: https://technitium.com/dns/
GitHub Repository: https://github.com/TechnitiumSoftware/DnsServer
Docker Hub: https://hub.docker.com/r/technitium/dns-server
Support: support@technitium.com

Change Log

Date	Change	Author
2025-11-20	Initial documentation created	Claude
2025-11-20	Updated container to latest image (661b3e38234c)	Claude