w3kllc/ddns repository overview

⁠Docker DynDNS Server

A modern, secure Dynamic DNS server with built-in threat intelligence and automatic IP blocking.

Perfect for home labs, security cameras, and any device that needs a stable DNS name with a dynamic IP address.

⁠🚀 Quick Start

docker run -d \
  --name dyndns \
  -p 8080:8080 \
  -p 53:53/udp \
  -v /path/to/data:/var/lib/dyndns \
  -e DDNS_ADMIN_LOGIN="admin:$(htpasswd -nbB admin yourpassword | cut -d: -f2)" \
  -e DDNS_SESSION_SECRET="$(openssl rand -base64 32)" \
  -e DDNS_DOMAINS=dyn.example.com \
  -e DDNS_PARENT_NS=ns1.example.com \
  -e DDNS_DEFAULT_TTL=300 \
  w3k-one/docker-ddns-server:latest

Or use Docker Compose:

version: '3.8'
services:
  dyndns:
    image: w3k-one/docker-ddns-server:latest
    container_name: dyndns
    restart: unless-stopped
    ports:
      - "8080:8080"
      - "53:53/udp"
    volumes:
      - ./data:/var/lib/dyndns
    environment:
      - DDNS_ADMIN_LOGIN=admin:$$apr1$$YourHashHere
      - DDNS_SESSION_SECRET=your-random-secret-here
      - DDNS_DOMAINS=dyn.example.com
      - DDNS_PARENT_NS=ns1.example.com
      - DDNS_DEFAULT_TTL=300
      - DDNS_POWERED_BY=ACME Inc
      - DDNS_POWERED_BY_URL=https://acme.inc

⁠✨ Key Features

⁠🔐 Advanced Security

• Automatic IP Blocking - Blocks IPs after 3 failed attempts for 7 days
• Threat Intelligence - Logs and analyzes attack patterns
• Session Authentication - Modern login page with secure cookies
• Smart HTTPS Enforcement - Auto-detects and enforces HTTPS via reverse proxy
• Dual Auth System - Session auth for admin, BasicAuth for devices

⁠🎯 Core Features

• RFC-Compatible - Works with routers, NVRs, and standard DynDNS clients
• Multi-Domain Support - Manage multiple domains from one instance
• CNAME Support - Create DNS aliases
• Wildcard DNS - Optional wildcard record support
• Fast Updates - Instant DNS record updates
• Complete Logging - Full audit trail of all IP updates

⁠🎨 Modern Interface

• Security Dashboard - Real-time threat monitoring and attack analysis
• Easy Management - Add/edit/delete hosts and CNAMEs
• Responsive Design - Works on desktop and mobile
• No Browser Popups - Beautiful login page instead of browser auth

⁠📊 Security Dashboard

Monitor your system's security in real-time:

• View blocked IPs and failed authentication attempts
• Analyze attack patterns and password proximity
• Manually unblock IPs when needed
• Track threat intelligence data

⁠🔌 Device Compatibility

Works with:

• DD-WRT / OpenWRT routers
• Hikvision / Dahua NVRs
• UniFi Dream Machine
• Synology NAS
• Any device supporting DynDNS protocol

⁠📝 Environment Variables

⁠Required

• DDNS_ADMIN_LOGIN - Admin credentials (htpasswd format)
• DDNS_DOMAINS - Comma-separated managed domains
• DDNS_PARENT_NS - Parent nameserver
• DDNS_DEFAULT_TTL - Default DNS TTL

⁠Recommended

• DDNS_SESSION_SECRET - Secret key for sessions (32+ bytes)
• DDNS_TITLE - Site title (default: "w3K DynDNS")
• DDNS_LOGOUT_URL - Redirect URL after logout

⁠Optional

• DDNS_ALLOW_WILDCARD - Enable wildcard DNS (default: false)
• DDNS_CLEAR_LOG_INTERVAL - Days to keep logs (default: 0 = forever)
• DDNS_POWERED_BY - Footer Credits
• DDNS_POWERED_BY_URL - Footer Credits URL

⁠🔧 Configuration Examples

⁠Generate Admin Password

htpasswd -nbB admin YourPasswordHere

⁠Generate Session Secret

openssl rand -base64 32

⁠Update Your IP (API)

curl -u username:password \
  "http://dyndns.example.com/nic/update?hostname=camera.example.com"

⁠Response Codes

• good <IP> - Update successful, IP changed
• nochg <IP> - Update successful, IP unchanged
• badauth - Invalid credentials
• blocked - IP address is blocked
• nohost - Hostname not found

⁠🛡️ Security Features Explained

⁠Why Log Passwords?

This is a single-user system designed for one administrator. All other login attempts are malicious by definition. We log failed credentials for threat intelligence:

• Analyze if attackers are close to real passwords
• Identify common attack patterns
• Enable proactive security measures
• No privacy violations (only malicious attempts logged)

Recommendation: Secure your database files with proper permissions.

⁠IP Blocking System

• Detection: Monitors failed authentication attempts
• Threshold: 3 failures within 72 hours
• Action: 7-day automatic block
• Response: Blocked IPs redirected to 127.0.0.1
• Management: Manual unblock via admin panel

⁠🌐 Reverse Proxy Setup

⁠Nginx Example

server {
    listen 443 ssl http2;
    server_name dyn.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

⁠Caddy Example

dyn.example.com {
    reverse_proxy localhost:8080
}

⁠🏗️ Architecture

• Language: Go 1.22
• Framework: Echo v4
• Database: SQLite (GORM)
• Sessions: Gorilla Sessions
• Base Image: golang:1.22-alpine

⁠📦 Volumes

• /var/lib/dyndns - SQLite database and persistent data

⁠🔌 Ports

• 8080/tcp - Web interface & API
• 53/udp - DNS server

⁠🏷️ Tags

• latest - Latest stable release
• 2.0.0 - Specific version
• 2.0 - Major version
• develop - Development branch (unstable)

⁠🤝 Support

• Issues: https://github.com/w3K-one/docker-ddns-server/issues⁠
• Discussions: https://github.com/w3K-one/docker-ddns-server/discussions⁠
• Documentation: https://github.com/w3K-one/docker-ddns-server⁠

⁠📜 License

MIT License - See LICENSE⁠

⁠🙏 Acknowledgments

Built with Echo Framework, GORM, and Gorilla Sessions. Inspired by the classic DynDNS protocol.

Made with ❤️ for homelabbers and self-hosters