dddns

Descoped Dynamic DNS - dddns

Most home networks receive dynamic public IP addresses via DHCP lease from ISPs, which can change on lease renewal or connection reset. Dynamic DNS (DDNS) solves this by automatically updating DNS records when your IP changes, keeping your domain (like home.example.com) always pointing to your current IP.

dddns is a lightweight, secure DDNS client specifically for AWS Route53, designed to run on resource-constrained devices like Ubiquiti Dream Machines. Perfect for VPN access, home servers, remote management, or any service that needs consistent access to your home network.

Features

🚀 Core Functionality

• AWS Route53 Integration - Updates DNS A records automatically (Route53 only)
• Smart IP Detection - Reliable public IP detection via checkip.amazonaws.com
• Change Detection - Only updates when IP actually changes
• Persistent Caching - Remembers last IP to minimize API calls
• Proxy/VPN Protection - Detects and prevents updates when behind proxy
• Dry Run Mode - Test changes without modifying DNS records
• Force Updates - Override cache when needed

🔒 Security

• Device-Specific Encryption - AES-256-GCM with hardware-derived keys
• Secure Credential Storage - Encrypted configs locked to specific hardware
• No Environment Variables - Credentials stored securely in config files
• File Permission Enforcement - Automatic 600/400 permissions
• Memory Wiping - Sensitive data cleared after use
• AWS Profile Support - Integrates with AWS CLI credentials

🖥️ Platform Support

• Ubiquiti Dream Machine - UDM/UDR with UniFi OS v3/v4
• Linux - AMD64, ARM64, ARM architectures
• macOS - Intel and Apple Silicon
• Windows - AMD64 and ARM64
• Docker - Container deployment ready
• Automatic Platform Detection - Adjusts paths and behavior per platform

📦 Deployment

• Single Binary - No dependencies, <10MB size
• Low Memory - <20MB runtime usage
• Boot Persistence - Survives firmware updates on UDM
• Cron Integration - Automated scheduling built-in
• One-Line Installation - Simple curl install for UDM
• Logging - Comprehensive logs with rotation

Quick Start

📋 Prerequisites: Need to set up AWS Route53 first? See the AWS Setup Guide for step-by-step instructions.

Ubiquiti Dream Machine (UDM/UDR)

# One-line installation
curl -fsL https://raw.githubusercontent.com/descoped/dddns/main/scripts/install-on-unifi-os.sh | bash

# Configure
dddns config init

# Test
dddns update --dry-run

⚠️ Compatibility Note: Check supported models and requirements before installation.

macOS

# Install via Homebrew
brew tap descoped/tap
brew install dddns

# Configure and run
dddns config init
dddns update

Linux

Debian/Ubuntu

# Download and install the .deb package
curl -LO https://github.com/descoped/dddns/releases/latest/download/dddns_Linux_x86_64.deb
sudo dpkg -i dddns_Linux_x86_64.deb

# For ARM64 systems:
curl -LO https://github.com/descoped/dddns/releases/latest/download/dddns_Linux_arm64.deb
sudo dpkg -i dddns_Linux_arm64.deb

Red Hat/CentOS/Fedora

# Install the .rpm package
sudo rpm -ivh https://github.com/descoped/dddns/releases/latest/download/dddns_Linux_x86_64.rpm

# For ARM64 systems:
sudo rpm -ivh https://github.com/descoped/dddns/releases/latest/download/dddns_Linux_arm64.rpm

Configure and run

dddns config init
dddns update

Commands

dddns update [--dry-run] [--force] [--quiet]  # Update DNS record
dddns config init                              # Interactive configuration
dddns config check                             # Validate configuration
dddns ip                                       # Show current public IP
dddns verify                                   # Check DNS vs current IP
dddns secure enable                            # Enable encrypted config
dddns --version                                # Show version

Documentation

• Quick Start - Get running in 5 minutes
• AWS Setup Guide - Start here if new to Route53 - Complete AWS setup
• Installation Guide - Detailed installation instructions
• Configuration - Configuration options
• Commands - Full command reference
• UDM Guide - Ubiquiti-specific setup
• Troubleshooting - Common issues and solutions

How It Works

flowchart LR
    A[Cron Job<br/>Every 30 min]:::start
    A -.-> B

    subgraph " "
        direction LR
        B[dddns update] --> C{Check IP}
        C --> D[Get IP]
        D --> E{Compare<br/>Cache}
        E -->|Changed| F[Query<br/>Route53]
        E -->|Same| G[Skip]
        F --> H{Need<br/>Update?}
        H -->|Yes| I[Update<br/>DNS]:::update
        H -->|No| G
        I --> J[Cache &<br/>Log]
    end

    J --> L[Exit]:::exit
    G --> L

    A ~~~ B
    J ~~~ L

    classDef start fill:#f9f,stroke:#333,stroke-width:2px
    classDef update fill:#9f9,stroke:#333,stroke-width:2px
    classDef exit fill:#ff9,stroke:#333,stroke-width:2px

The flow ensures minimal API calls and only updates DNS when necessary, making it efficient and ISP-friendly.

💡 Cost Tip: Running your own dynamic DNS with AWS Route53 costs approximately USD 0.50 per month for a hosted zone. This makes dddns a very affordable solution for reliable home network access.

Development

Prerequisites

• Go 1.22+
• Make

Building

# Clone repository
git clone https://github.com/descoped/dddns.git
cd dddns

# Build for current platform
just build

# Race build for local dev
just dev

# Run tests
just test

# Cross-platform release binaries are produced by GoReleaser on every
# tag push — see .github/workflows/goreleaser.yml. To exercise it
# locally, install goreleaser and run `goreleaser build --snapshot`.

Project Structure

cmd/                  # CLI commands
internal/
├── config/          # Configuration management
├── crypto/          # Device-specific encryption
├── dns/             # Route53 client
├── profile/         # Platform detection
└── version/         # Version information

Release Process

Releases use GoReleaser with git tags:

git tag v1.0.0
git push origin v1.0.0

GitHub Actions automatically builds and releases binaries for all platforms.

Configuration

Need AWS Route53? Follow the AWS Setup Guide to create your hosted zone and IAM credentials first.

Example Configuration

# ~/.dddns/config.yaml
aws_region: us-east-1
hosted_zone_id: ZXXXXXXXXXXXXX  # Get this from AWS Setup Guide
hostname: home.example.com
ttl: 300

# AWS credentials (or use AWS profile)
access_key: AKIAXXXXXXXXXXXXXX
secret_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Secure Configuration

For enhanced security, use encrypted configuration:

# Convert to encrypted config
dddns secure enable

# Config is now encrypted with device-specific key
# Cannot be moved between devices

Support

Reporting Issues

If you encounter any problems:

1. Check the Troubleshooting Guide first
2. Search existing issues to see if it's already reported
3. Create a new issue with:
   • Your platform (UDM model, OS version)
   • dddns version (dddns --version)
   • Error messages or logs
   • Steps to reproduce

Getting Help

• 📖 Documentation - Comprehensive guides
• 🐛 Issues - Report bugs or request features
• 💬 Discussions - Ask questions and share ideas

Contributing

We welcome contributions! Whether it's bug fixes, new features, or documentation improvements, your help is appreciated.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (just test)
5. Commit your changes (git commit -m 'feat: add amazing feature')
6. Push to your branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Guidelines

• Follow Go best practices and conventions
• Add tests for new functionality
• Update documentation as needed
• Keep commits atomic and well-described
• Ensure all tests pass before submitting PR

Areas for Contribution

• 🐛 Bug fixes
• 📚 Documentation improvements
• 🧪 Test coverage expansion
• 🔧 Performance optimizations
• 🎨 Code refactoring
• 🌐 Support for more DNS providers

License

This project is licensed under the MIT License - see the LICENSE file for details.

Note: This tool is specifically designed for AWS Route53. If you need support for other DNS providers, please open an issue to discuss potential implementation.