English | 简体中文

TrustDDNS-Cloudflare

TrustDDNS is an asyncio-based Cloudflare DDNS client written in python. Features concurrent multi-source IP voting, batch DNS record updates and SMTP notifications. Easy to set up — just run ‘python main.py’.

🚀 TrustDDNS

A high-performance, scalable, and easy-to-use Cloudflare DDNS client that features multi-source IP acquisition with intelligent verification, batch DNS updates, and optional email notifications.

🧩 Features & Highlights

⚡ 1. Fully Async

• Built with asyncio + aiohttp
• Concurrent IP fetching, concurrent DDNS updates, and concurrent SMTP email notifications
• Batch execution with automatic sharding to prevent rate limiting

🗳️ 2. Intelligent IP Voting

✔ Senate Mode (Majority Voting)

• Multiple IP sources fetch simultaneously → final IP decided by majority vote

✔ Strict-source Mode (Per-source Voting)

• Each source counts votes independently to avoid instability from any single provider
• true: When multiple URLs under the same source conflict, the source abstains;false: Each URL votes independently

👉 Improves the accuracy and reliability of public IP detection while maintaining high speed through coroutines.

🌐 3. Deep Cloudflare DNS Update Support

• Supports multiple accounts and multiple zones
• Full batch DNS record updates
• Advanced support for cloudflare.api.DNS.update:
  • Automatic completion of record_id / name / type
  • Supports renaming with new_name
  • Updates content, type, comment, proxied, etc.
  • Automatically injects correct A / AAAA records based on IP version
• Built-in features:
  • Is async + concurrency control to prevent hitting rate limits
  • Automatic retries
  • Clear status tracking (ok / error / ready)

📬 4. Optional Email Notifications

• Supports custom SMTP configuration (TLS/SSL)
• Sends notifications when IP changes are detected
• Features:
  • HTML and plain-text templates powered by Jinja2
  • Customizable content and templates
  • Multi-language support (English and Chinese messages provided, easily extensible)

🧾 5. Persistent Status Management

• Automatically maintains state in status.json
• Records:
  • Last known IP
  • DDNS update status
  • Email notification status
• Supports failure recovery and retry logic

⚙️ Usage Guide

1. Quick Start

1. Install uv (if not already installed):

   macOS / Linux:

   curl -LsSf <https://astral.sh/uv/install.sh> | sh

   Windows (PowerShell):

   powershell -ExecutionPolicy ByPass -c "irm <https://astral.sh/uv/install.ps1> | iex"

2. Clone the repository and enter the directory

   git clone <repository-url>
   cd TrustDDNS

3. Sync the project environment

   uv sync

4. Copy and configure the files

   cp config.example.ini config.ini
   cp ddns.example.json ddns.json
   # Optional: required if email notification is enabled
   cp smtp.example.json smtp.json

5. Test run manually

   uv run python main.py

6. Set up scheduled execution (recommended for Linux/macOS using cron):

   Edit crontab:

   crontab -e

   Add the following (replace paths with your actual absolute paths):

   # TrustDDNS - Run every 5 minutes
   SHELL=/bin/bash
   PATH=/usr/local/bin:/usr/bin:/bin:/home/yourusername/.cargo/bin
   
   */5 * * * * cd /home/yourusername/TrustDDNS && uv run python main.py >> ddns.log
   

2. Basic Configuration

Edit ./config.ini to enable/disable IP detection, DDNS updates, and email notifications.

See config.example.ini for detailed options.

3. DDNS Configuration

To enable DDNS updates, configure ./ddns.json (see ddns.example.json for examples).

You can specify DNS records by either name or record_id. Any additional fields in the configuration will be passed as update parameters to Cloudflare. The new_name field allows renaming a record.

When an IP change is detected, the script automatically updates the content field with the correct IPv4 or IPv6 address based on record type.

4. Email Notifications

To receive email alerts when the IP changes, configure ./smtp.json (see smtp.example.json).

Enable SMTP in your email provider, obtain the token/password, and fill in the configuration accordingly.

📜 License

MIT