🌐 Cloudflare DDNS Updater

A Python-based Dynamic DNS updater for Cloudflare that automatically updates your DNS records with your current public IP address. Perfect for home servers, self-hosted services, or any situation where you need to keep DNS records synchronized with a changing IP address.

✨ Features

• 🔄 Automatic IP Detection: Fetches your current public IPv4 and IPv6 addresses
• 🎯 Smart Updates: Only updates DNS records when IP addresses actually change
• 🏗️ Multi-Zone Support: Manage DNS records across multiple Cloudflare zones
• ⚡ Efficient Operations: Creates missing records and updates existing ones intelligently
• 🔁 Continuous Monitoring: Run once or continuously with configurable intervals
• 🛡️ Error Resilience: Automatic retry logic with graceful error handling

🚀 Quick Start

Prerequisites

• Python 3.13+
• Cloudflare account with API access Cloudflare Dashboard
• Domain(s) managed by Cloudflare

Installation

1. Clone the repository:

   git clone CloudFlare-DDNS
   cd cloudflare-ddns

2. Install dependencies:

   # Using uv (recommended)
   uv sync
   
   # Or using pip
   pip install -r requirements.txt

3. Configure your settings:

   cp config.json.example config.json

4. Edit config.json with your Cloudflare API key and DNS records:

   {
       "api_key": "your_cloudflare_api_token",
       "update_interval_minutes": 10,
       "ddns_records": {
           "your_zone_id": [
               {
                   "type": "A",
                   "name": "home.example.com",
                   "proxy": false
               },
               {
                   "type": "AAAA",
                   "name": "home.example.com",
                   "proxy": false
               }
           ]
       }
   }

Usage

Run Continuously (Default)

python main.py

Runs every 10 minutes (or as configured in config.json)

Run Once

python main.py --once

Performs a single update and exits

Custom Interval

python main.py --interval 30

Runs continuously with 30-minute intervals

⚙️ Configuration

config.json Structure

{
    "api_key": "your_cloudflare_api_token",
    "update_interval_minutes": 10,
    "ddns_records": {
        "zone_id_1": [
            {
                "type": "A",
                "name": "subdomain.example.com",
                "proxy": false,
                "ttl": 300,
                "comment": "Home server A record",
                "tags": ["ddns", "home"]
            }
        ],
        "zone_id_2": [
            {
                "type": "AAAA",
                "name": "ipv6.example.com",
                "proxy": true
            }
        ]
    }
}

Configuration Fields

Field	Type	Required	Description
api_key	string	✅	Cloudflare API token with DNS edit permissions
update_interval_minutes	number	❌	Update interval in minutes (default: 10)
ddns_records	object	✅	DNS records organized by zone ID

DNS Record Fields

Field	Type	Required	Description
type	string	✅	Record type: "A" or "AAAA"
name	string	✅	Full domain name (e.g., "home.example.com")
proxy	boolean	❌	Enable Cloudflare proxy (default: false)
ttl	number	❌	TTL in seconds (default: auto)
comment	string	❌	Record comment for documentation
tags	array	❌	Array of tags for organization

🔑 Getting Your Cloudflare API Token

1. Go to Cloudflare Dashboard
2. Click "Create Token"
3. Use "Edit zone DNS" template or create custom token with:
   • Permissions: Zone:DNS:Edit
   • Zone Resources: Include specific zones or all zones
4. Copy the generated token to your config.json

📁 Project Structure

cloudflare-ddns/
├── main.py          # Main application entry point
├── ddns.py          # DNS record management functions
├── get_ip.py        # IP address detection utilities
├── settings.py      # Configuration and Pydantic models
├── config.json      # Configuration file (create from example)
├── pyproject.toml   # Project dependencies and metadata
├── uv.lock          # Dependency lock file
└── README.md        # This file

🔧 Development

File Descriptions

• main.py: Application entry point with CLI argument parsing and update loop
• ddns.py: Core DNS operations (create, update, list records)
• get_ip.py: IP address detection from external services
• settings.py: Configuration loading and Pydantic data models
• config.json: User configuration file

Adding New Features

The codebase uses modern Python practices:

• Async/await for non-blocking operations
• Pydantic models for data validation
• Type hints throughout for better IDE support
• Modular design for easy extension

🐛 Troubleshooting

Common Issues

API Token Errors:

• Verify your API token has Zone:DNS:Edit permissions
• Check that the token includes access to your zones
• Ensure the token hasn't expired

Zone ID Not Found:

• Find your Zone ID in Cloudflare Dashboard → [Your Domain] → Overview → API section (Scroll Down)
• Verify the Zone ID matches exactly in config.json

DNS Record Not Updating:

• Check that the record name matches exactly (including subdomain)
• Verify record type (A for IPv4, AAAA for IPv6)
• Ensure your IP address detection is working

Network Issues:

• The tool uses ipify.org for IP detection
• Check your internet connection and firewall settings

Debug Mode

Run with Python's verbose output to see detailed information:

python -v main.py --once

📊 Output Examples

Successful Update

Cloudflare DDNS Updater Starting...
==================================================
Mode: Continuous updates every 10 minutes
Press Ctrl+C to stop the updater

Update #1
Time: 2025-08-06 14:30:00
Fetching your public IP address...
Your public IPv4 is: 203.0.113.1, IPv6 is: 2001:db8::1
Updating DNS records...
	Updating records for zone ID: 13dfc6deb849d252c89be61630e9a5f8
	Existing records: 2, New records: 0
	✓ Record home.example.com (A) already has the correct IP address
	↻ Updating record home.example.com (AAAA) to new IP address...
	✓ No new records to create for zone ID: 13dfc6deb849d252c89be61630e9a5f8
DNS update completed successfully!
Waiting 10 minutes until next update...
==================================================

📄 License

This project is open source. Feel free to use, modify, and distribute according to your needs.

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

---

Made with ❤️ for the self-hosting community