Python DynDNS for AWS Route 53

A lightweight, Docker-packaged Dynamic DNS service that automatically updates one or more A-records in AWS Route 53 via a simple HTTP endpoint. Perfect for home networks, small offices, or any environment with a dynamic IP address that needs reliable DNS resolution.

🚀 Features

• 🔄 Multiple DNS Records: Update multiple domain names simultaneously with a single API call
• 💾 Stateful Operation: Remembers the last known IP to avoid unnecessary AWS API calls and reduce costs
• 🐳 Fully Containerized: Runs in an isolated Docker container with Docker Compose for easy deployment
• ⚙️ Environment-Based Configuration: All settings managed via environment variables - no code changes needed
• 📝 Comprehensive Logging: Rotating log files with detailed request tracking and error reporting
• 🔒 Secure: Uses AWS IAM credentials for secure Route 53 access
• ⚡ Lightweight: Minimal resource footprint with Python Flask backend

📋 Prerequisites

Before deploying this service, ensure you have the following:

• Docker (version 20.10 or higher)
• Docker Compose (version 2.0 or higher)
• AWS Account with Route 53 access
• AWS IAM User with Route 53 permissions

Required AWS Permissions

Your AWS IAM user needs the following Route 53 permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["route53:ChangeResourceRecordSets", "route53:GetChange"],
      "Resource": [
        "arn:aws:route53:::hostedzone/*",
        "arn:aws:route53:::change/*"
      ]
    }
  ]
}

🛠️ Installation & Setup

1. Clone the Repository

git clone https://github.com/mainvoid007/dyndns.git
cd dyndns

2. Create Environment Configuration

Create a .env file in the project root:

# AWS Configuration
AWS_ACCESS_KEY_ID=your_aws_access_key_here
AWS_SECRET_ACCESS_KEY=your_aws_secret_key_here
AWS_DEFAULT_REGION=eu-west-1

# Route 53 Configuration
HOSTED_ZONE_ID=Z1234567890ABCDEFGHIJ
RECORD_NAMES=subdomain1.yourdomain.com,subdomain2.yourdomain.com

# Service Configuration
HOST_PORT=8005

3. Configuration Details

Variable	Description	Example
AWS_ACCESS_KEY_ID	Your AWS access key	AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY	Your AWS secret key	wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_DEFAULT_REGION	AWS region for Route 53	eu-west-1, us-east-1
HOSTED_ZONE_ID	Route 53 hosted zone ID	Z1234567890ABCDEFGHIJ
RECORD_NAMES	Comma-separated list of DNS records	home.yourdomain.com,office.yourdomain.com
HOST_PORT	Port to expose the service on	8005

4. Deploy the Service

# Build and start the service
docker-compose up -d

# Check service status
docker-compose ps

# View logs
docker-compose logs -f

📖 Usage

API Endpoints

Health Check

curl http://localhost:8005/

Response: DynDNS Service is active.

Update IP Address

curl "http://localhost:8005/update?ip=203.0.113.1"

Response Examples:

✅ Success:

{
  "status": "success",
  "ip": "203.0.113.1"
}

🔄 No Change:

{
  "status": "no_change",
  "ip": "203.0.113.1"
}

❌ Error:

{
  "status": "error",
  "message": "Missing 'ip' parameter."
}

Integration Examples

Router Integration (DD-WRT/OpenWRT)

Add this to your router's startup script:

# Get current WAN IP and update DNS
WAN_IP=$(curl -s ifconfig.me)
curl -s "http://your-server:8005/update?ip=$WAN_IP"

Cron Job (Linux/Mac)

# Add to crontab (runs every 5 minutes)
*/5 * * * * curl -s "http://localhost:8005/update?ip=$(curl -s ifconfig.me)" > /dev/null 2>&1

PowerShell Script (Windows)

$ip = (Invoke-WebRequest -Uri "https://ifconfig.me" -UseBasicParsing).Content
Invoke-WebRequest -Uri "http://localhost:8005/update?ip=$ip" -UseBasicParsing

📊 Monitoring & Logs

View Service Logs

# Real-time logs
docker-compose logs -f

# Recent logs
docker-compose logs --tail=100

Log Files

• Application Logs: logs/requests.log
• State File: logs/last_ip.log

Log Format

2024-01-15 10:30:45,123 - INFO - Update request from IP 192.168.1.100 with parameters: {'ip': '203.0.113.1'}
2024-01-15 10:30:45,456 - INFO - IP address change detected: Old IP=203.0.113.0, New IP=203.0.113.1
2024-01-15 10:30:46,789 - INFO - Route 53 and state successfully updated to 203.0.113.1

🔧 Troubleshooting

Common Issues

Service Won't Start

# Check Docker logs
docker-compose logs

# Verify environment variables
docker-compose config

AWS Authentication Errors

• Verify your AWS credentials in the .env file
• Ensure your IAM user has Route 53 permissions
• Check that the AWS region is correct

DNS Updates Not Working

• Verify the HOSTED_ZONE_ID is correct
• Ensure RECORD_NAMES are properly formatted (comma-separated)
• Check that the domain names exist in your Route 53 hosted zone

Debug Mode

To run in debug mode, modify the Dockerfile:

CMD ["python", "app.py", "--debug"]

🔒 Security Considerations

• Never commit your .env file - it's already in .gitignore
• Use IAM roles instead of access keys when possible
• Restrict network access to the service port
• Regularly rotate your AWS credentials
• Monitor AWS CloudTrail for API usage

📈 Performance & Cost Optimization

• Stateful operation prevents unnecessary API calls
• Rotating logs prevent disk space issues
• Lightweight container minimizes resource usage
• Efficient Route 53 updates using batch operations

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🆘 Support

If you encounter any issues or have questions:

1. Check the troubleshooting section
2. Review the logs using docker-compose logs
3. Open an issue on GitHub with detailed information

---

Made with ❤️ for the community