timothyjmiller/cloudflare-ddns repository overview

⁠

⁠🌍 Cloudflare DDNS

Access your home network remotely via a custom domain name without a static IP!

A feature-complete dynamic DNS client for Cloudflare, written in Rust. The smallest and most memory-efficient open-source Cloudflare DDNS Docker image available — ~1.1 MB image size and ~3.5 MB RAM at runtime, smaller and leaner than Go-based alternatives. Built as a fully static binary from scratch with zero runtime dependencies.

Configure everything with environment variables. Supports notifications, heartbeat monitoring, WAF list management, flexible scheduling, and more.

⁠✨ Features

• 🔍 Multiple IP detection providers — Cloudflare Trace, Cloudflare DNS-over-HTTPS, ipify, local interface, custom URL, or static IPs
• 📡 IPv4 and IPv6 — Full dual-stack support with independent provider configuration
• 🌐 Multiple domains and zones — Update any number of domains across multiple Cloudflare zones
• 🃏 Wildcard domains — Support for *.example.com records
• 🌍 Internationalized domain names — Full IDN/punycode support (e.g. münchen.de)
• 🛡️ WAF list management — Automatically update Cloudflare WAF IP lists
• 🔔 Notifications — Shoutrrr-compatible notifications (Discord, Slack, Telegram, Gotify, Pushover, generic webhooks)
• 💓 Heartbeat monitoring — Healthchecks.io and Uptime Kuma integration
• ⏱️ Cron scheduling — Flexible update intervals via cron expressions
• 🧪 Dry-run mode — Preview changes without modifying DNS records
• 🧹 Graceful shutdown — Signal handling (SIGINT/SIGTERM) with optional DNS record cleanup
• 💬 Record comments — Tag managed records with comments for identification
• 🎯 Managed record regex — Control which records the tool manages via regex matching
• 🎨 Pretty output with emoji — Configurable emoji and verbosity levels
• 🔒 Zero-log IP detection — Uses Cloudflare's cdn-cgi/trace⁠ by default
• 🏠 CGNAT-aware local detection — Filters out shared address space (100.64.0.0/10) and private ranges
• 🚫 Cloudflare IP rejection — Optionally reject Cloudflare anycast IPs to prevent incorrect DNS updates
• 🤏 Tiny static binary — ~1.1 MB Docker image built from scratch, zero runtime dependencies

⁠🚀 Quick Start

docker run -d \
  --name cloudflare-ddns \
  --restart unless-stopped \
  --network host \
  -e CLOUDFLARE_API_TOKEN=your-api-token \
  -e DOMAINS=example.com,www.example.com \
  timothyjmiller/cloudflare-ddns:latest

That's it. The container detects your public IP and updates the DNS records for your domains every 5 minutes.

⁠🔑 Authentication

To generate an API token, go to your Cloudflare Profile⁠ and create a token capable of Edit DNS.

⁠🌐 Domains

Wildcard domains are supported: *.example.com

At least one of DOMAINS, IP4_DOMAINS, IP6_DOMAINS, or WAF_LISTS must be set.

⁠🔍 IP Detection Providers

Available providers:

⁠🚫 Cloudflare IP Rejection

Some IP detection providers occasionally return a Cloudflare anycast IP instead of your real public IP. When this happens, your DNS record gets updated to point at Cloudflare infrastructure rather than your actual address.

Setting REJECT_CLOUDFLARE_IPS=true prevents this. Each update cycle fetches Cloudflare's published IP ranges⁠ and skips any detected IP that falls within them. A warning is logged for every rejected IP.

⁠⏱️ Scheduling

Schedule formats:

• @every 5m — Every 5 minutes
• @every 1h — Every hour
• @every 30s — Every 30 seconds
• @once — Run once and exit

When UPDATE_CRON=@once, UPDATE_ON_START must be true and DELETE_ON_STOP must be false.

⁠📝 DNS Record Settings

The PROXIED variable supports boolean expressions:

Operators: is(), sub(), !, &&, ||, ()

⁠🛡️ WAF Lists

WAF list names must match the pattern [a-z0-9_]+.

⁠🔔 Notifications (Shoutrrr)

Supported services:

Notifications are sent when DNS records are updated, created, deleted, or when errors occur.

⁠💓 Heartbeat Monitoring

Heartbeats are sent after each update cycle. On failure, a fail signal is sent. On shutdown, an exit signal is sent.

⁠⏳ Timeouts

⁠🖥️ Output

⁠🏁 CLI Flags

⁠📋 All Environment Variables

⁠🚢 Deployment

⁠🐳 Docker Compose

version: '3.9'
services:
  cloudflare-ddns:
    image: timothyjmiller/cloudflare-ddns:latest
    container_name: cloudflare-ddns
    security_opt:
      - no-new-privileges:true
    network_mode: 'host'
    environment:
      - CLOUDFLARE_API_TOKEN=your-api-token
      - DOMAINS=example.com,www.example.com
      - PROXIED=true
      - IP6_PROVIDER=none
      - HEALTHCHECKS=https://hc-ping.com/your-uuid
    restart: unless-stopped

⁠☸️ Kubernetes

The included manifest uses the legacy JSON config mode. Create a secret containing your config.json and apply:

kubectl create secret generic config-cloudflare-ddns --from-file=config.json -n ddns
kubectl apply -f k8s/cloudflare-ddns.yml

⁠🐧 Linux + Systemd

1. Build and install:

cargo build --release
sudo cp target/release/cloudflare-ddns /usr/local/bin/

1. Copy the systemd units from the systemd/ directory:

sudo cp systemd/cloudflare-ddns.service /etc/systemd/system/
sudo cp systemd/cloudflare-ddns.timer /etc/systemd/system/

1. Place a config.json at /etc/cloudflare-ddns/config.json (the systemd service uses legacy config mode).

2. Enable the timer:

sudo systemctl enable --now cloudflare-ddns.timer

The timer runs the service every 15 minutes (configurable in cloudflare-ddns.timer).

⁠🔨 Building from Source

cargo build --release

The binary is at target/release/cloudflare-ddns.

⁠🐳 Docker builds

# Single architecture (linux/amd64)
./scripts/docker-build.sh

# Multi-architecture (linux/amd64, linux/arm64, linux/ppc64le)
./scripts/docker-build-all.sh

⁠💻 Supported Platforms

• 🐳 Docker⁠ (amd64, arm64, ppc64le)
• 🐙 Docker Compose⁠
• ☸️ Kubernetes⁠
• 🐧 Systemd⁠
• 🍎 macOS, 🪟 Windows, 🐧 Linux — anywhere Rust compiles

⁠📁 Legacy JSON Config File

For backwards compatibility, cloudflare-ddns still supports configuration via a config.json file. This mode is used automatically when no CLOUDFLARE_API_TOKEN environment variable is set.

⁠🚀 Quick Start

cp config-example.json config.json
# Edit config.json with your values
cloudflare-ddns

⁠🔑 Authentication

Use either an API token (recommended) or a legacy API key:

"authentication": {
  "api_token": "Your cloudflare API token with Edit DNS capability"
}

Or with a legacy API key:

"authentication": {
  "api_key": {
    "api_key": "Your cloudflare API Key",
    "account_email": "The email address you use to sign in to cloudflare"
  }
}

⁠📡 IPv4 and IPv6

Some ISP provided modems only allow port forwarding over IPv4 or IPv6. Disable the interface that is not accessible:

"a": true,
"aaaa": true

⁠⚙️ Config Options

Each zone entry contains:

Subdomain entries can be a simple string or a detailed object:

"subdomains": [
  "",
  "@",
  "www",
  { "name": "vpn", "proxied": true }
]

Use "" or "@" for the root domain. Do not include the base domain name.

⁠🔄 Environment Variable Substitution

In the legacy config file, values can reference environment variables with the CF_DDNS_ prefix:

{
  "cloudflare": [{
    "authentication": {
      "api_token": "${CF_DDNS_API_TOKEN}"
    },
    ...
  }]
}

⁠📠 Example: Multiple Subdomains

{
  "cloudflare": [
    {
      "authentication": {
        "api_token": "your-api-token"
      },
      "zone_id": "your_zone_id",
      "subdomains": [
        { "name": "", "proxied": true },
        { "name": "www", "proxied": true },
        { "name": "vpn", "proxied": false }
      ]
    }
  ],
  "a": true,
  "aaaa": true,
  "purgeUnknownRecords": false,
  "ttl": 300
}

⁠🌐 Example: Multiple Zones

{
  "cloudflare": [
    {
      "authentication": { "api_token": "your-api-token" },
      "zone_id": "first_zone_id",
      "subdomains": [
        { "name": "", "proxied": false }
      ]
    },
    {
      "authentication": { "api_token": "your-api-token" },
      "zone_id": "second_zone_id",
      "subdomains": [
        { "name": "", "proxied": false }
      ]
    }
  ],
  "a": true,
  "aaaa": true,
  "purgeUnknownRecords": false
}

⁠🐳 Docker Compose (legacy config file)

version: '3.9'
services:
  cloudflare-ddns:
    image: timothyjmiller/cloudflare-ddns:latest
    container_name: cloudflare-ddns
    security_opt:
      - no-new-privileges:true
    network_mode: 'host'
    volumes:
      - /YOUR/PATH/HERE/config.json:/config.json
    restart: unless-stopped

⁠🏁 Legacy CLI Flags

In legacy config mode, use --repeat to run continuously (the TTL value is used as the update interval):

cloudflare-ddns --repeat
cloudflare-ddns --repeat --dry-run

⁠🔗 Helpful Links

• 🔑 Cloudflare API token⁠
• 🆔 Cloudflare zone ID⁠
• 📋 Cloudflare zone DNS record ID⁠

⁠📜 License

This project is licensed under the GNU General Public License, version 3 (GPLv3).

⁠👨‍💻 Author

Timothy Miller

View my GitHub profile 💡⁠

View my personal website 💻⁠