swaya1125/cloudflare-ddns repository overview

⁠Cloudflare DDNS Updater

A Python-based Dynamic DNS (DDNS) updater for Cloudflare that automatically updates DNS records with your current public IP address. This tool focuses on IP address updates only and preserves existing TTL and proxy settings.

⁠Features

• Automatic IP Detection: Fetches your current public IPv4 and optionally IPv6 addresses
• Selective Updates: Only updates DNS records when IP addresses actually change
• Auto-Discovery: Automatically discover and update all A records in your zone
• Manual Record Selection: Specify exact DNS records to update
• IPv6 Support: Optional AAAA record updates
• Continuous Monitoring: Run continuously with configurable intervals
• Docker Support: Runs seamlessly in Docker containers
• Comprehensive Logging: Detailed logging with adjustable verbosity
• Error Handling: Robust error handling with graceful recovery

⁠Key Behavior

• Preserves Existing Settings: The updater only changes the IP address content of DNS records
• TTL Preservation: Existing TTL values are maintained
• Proxy Status Preservation: Existing proxy (orange cloud) settings are preserved
• Non-Destructive: Only updates the IP address field, leaving all other record properties unchanged

⁠Quick Start

⁠Using Docker (Recommended)

1. Create a .env file with your configuration:

API_TOKEN=your_cloudflare_api_token
ZONE_NAME=example.com
RECORDS=subdomain.example.com,another.example.com

1. Run with Docker:

docker run -d --env-file .env your-registry/cloudflare-ddns

⁠Using Python Directly

1. Install dependencies:

pip install -r requirements.txt

1. Set environment variables and run:

export API_TOKEN=your_cloudflare_api_token
export ZONE_NAME=example.com
export RECORDS=subdomain.example.com
python main.py

⁠Configuration

⁠Required Environment Variables

⁠DNS Record Configuration

Choose one of these approaches:

⁠Option 1: Manual Record Selection

⁠Option 2: Auto-Discovery

⁠Optional Configuration

⁠Usage Examples

⁠Basic Setup

Update specific DNS records every 5 minutes:

API_TOKEN=your_token
ZONE_NAME=example.com
RECORDS=home.example.com,vpn.example.com
INTERVAL=300

⁠Auto-Discovery Mode

Automatically update all A records in your zone:

API_TOKEN=your_token
ZONE_NAME=example.com
AUTO_DISCOVER=true
INTERVAL=600

⁠IPv6 Support

Enable both IPv4 and IPv6 updates:

API_TOKEN=your_token
ZONE_NAME=example.com
RECORDS=home.example.com
UPDATE_AAAA=true

⁠One-Time Update

Run once and exit (useful for cron jobs):

API_TOKEN=your_token
ZONE_NAME=example.com
RECORDS=home.example.com
INTERVAL=0

⁠Docker Deployment

⁠Docker Compose

version: '3.8'
services:
  cloudflare-ddns:
    image: your-registry/cloudflare-ddns
    restart: unless-stopped
    environment:
      - API_TOKEN=your_cloudflare_api_token
      - ZONE_NAME=example.com
      - RECORDS=home.example.com,vpn.example.com
      - INTERVAL=300
      - VERBOSE=false

⁠Building the Image

docker build -t cloudflare-ddns .

⁠API Token Setup

1. Go to Cloudflare API Tokens⁠
2. Click "Create Token"
3. Use "Custom token" with these permissions:
   • Zone - Zone:Read - Include All zones
   • Zone - DNS:Edit - Include Specific zone:your-domain.com

⁠Logging

The application provides comprehensive logging:

• INFO: Normal operation status, IP changes, and updates
• WARNING: Non-critical issues like missing records
• ERROR: Failed operations and configuration issues
• DEBUG: Detailed operation information (when VERBOSE=true)

Example log output:

2023-10-09 12:00:00 - cloudflare-ddns - INFO - Starting Cloudflare DDNS updater
2023-10-09 12:00:00 - cloudflare-ddns - INFO - Zone: example.com
2023-10-09 12:00:01 - cloudflare-ddns - INFO - Current IPv4 address: 203.0.113.42
2023-10-09 12:00:01 - cloudflare-ddns - INFO - Update A home.example.com: 203.0.113.1 → 203.0.113.42
2023-10-09 12:00:02 - cloudflare-ddns - INFO - No change for A vpn.example.com (still 203.0.113.42)

⁠Error Handling

The application includes robust error handling:

• API Errors: Retries and detailed error messages for Cloudflare API issues
• Network Issues: Graceful handling of connectivity problems
• Configuration Errors: Clear validation and error messages
• Graceful Shutdown: Proper cleanup on SIGINT/SIGTERM

⁠Security Considerations

• Store API tokens securely (use Docker secrets, environment files with restricted permissions)
• Use least-privilege API tokens (Zone:Read + DNS:Edit for specific zones only)
• Regularly rotate API tokens
• Monitor logs for unauthorized access attempts

⁠Troubleshooting

⁠Common Issues

1. "Zone not found": Verify ZONE_NAME matches exactly with Cloudflare
2. "Token lacks access": Ensure API token has correct permissions
3. "No records found": Check record names and auto-discovery settings
4. Network timeouts: Verify internet connectivity and IP service URLs

⁠Debug Mode

Enable verbose logging for troubleshooting:

VERBOSE=true

⁠License

This project is open source. See the LICENSE file for details.

⁠Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.