Open-Source DevOps · timothymiller

cloudflare-ddns

A lightweight Rust-based dynamic DNS client for Cloudflare that automatically updates DNS records when your public IP changes. Designed for self-hosted setups, it runs in ~1.1 MB Docker containers with minimal memory overhead and supports IPv4/IPv6, multiple domains, notifications, and WAF list management.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/timothymiller/cloudflare-ddns

4.2k

GitHub stars

418

Forks

Rust

Primary language

GPL-3.0

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	timothymiller/cloudflare-ddns
Owner	timothymiller
Primary language	Rust
License	GPL-3.0 — OSI-approved
Stars	4.2k
Forks	418
Open issues	10
Latest release	v2.1.2 (2026-04-30)
Last updated	2026-07-03
Source	https://github.com/timothymiller/cloudflare-ddns

What cloudflare-ddns is

Static Rust binary compiled to scratch Docker images with zero runtime dependencies. Provides flexible IP detection (Cloudflare Trace, DNS-over-HTTPS, ipify, local interfaces, custom URLs), cron-based scheduling, Shoutrrr notification integration, and Cloudflare API automation for DNS, WAF lists, and health monitoring endpoints.

Quickstart

Get the cloudflare-ddns source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/timothymiller/cloudflare-ddns.git2cd cloudflare-ddns3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Home lab or self-hosted server access

Enables reliable remote access to home networks via custom domain without static IP. Ideal for NAS, media servers, or home automation platforms needing consistent DNS resolution.

Resource-constrained environments

Minimal footprint (~1.1 MB, ~3.5 MB RAM) makes it suitable for Raspberry Pi, ARM devices, VPS with tight constraints, or container orchestration with strict resource budgets.

Multi-domain or multi-zone automation

Manages numerous Cloudflare domains, wildcard records, and WAF lists from single configuration. Useful for multi-tenant setups, DNS failover scenarios, or mass domain management.

Implementation considerations

Requires Cloudflare API token with 'Edit DNS' capability—generate via Cloudflare Profile dashboard and store securely (Docker secrets or mounted files recommended).
IPv6 detection requires `--network host` in Docker due to kernel networking constraints; IPv4-only deployments can use bridge networking.
By default rejects detected IPs within Cloudflare's published IP ranges to prevent misconfiguration; disable only if you understand the implications.
Update frequency configurable via cron expressions (@every 5m default); shorter intervals increase API calls and rate-limit risk; monitor Cloudflare API quota.
Supports graceful shutdown with optional DNS record cleanup (DELETE_ON_STOP) and automatic cleanup on IP detection failure (DELETE_ON_FAILURE=true default).

When to avoid it — and what to weigh

Non-Cloudflare DNS provider — This tool is tightly coupled to Cloudflare's API. If your domains are hosted elsewhere (Route53, Azure DNS, Namecheap, etc.), you need a different DDNS client.
Strict GPLv3 incompatibility requirements — GPLv3 license requires derivative works and distributions to be open-source. If your deployment model or proprietary integration violates GPL terms, this tool is unsuitable without separate licensing review.
Need for commercial support SLA — Community-maintained project with no official commercial support, guaranteed response times, or vendor accountability. Critical production environments requiring guaranteed uptime support should evaluate commercial alternatives.
Complex conditional IP detection logic — IP detection is deterministic and rule-based (single provider per IP version). If you need complex failover chains, weighted provider selection, or stateful IP history tracking, this may be insufficient.

License & commercial use

GPLv3 (GNU General Public License v3.0). Copyleft license requiring source code disclosure, attribution, and derivative works to remain open-source under identical terms.

GPLv3 is a strong copyleft license. Commercial use is permitted for internal operations (e.g., running in your own infrastructure), but distribution of modified versions or integration into closed-source products requires either open-sourcing those modifications or obtaining separate commercial licensing. Requires review if you plan to redistribute, integrate into proprietary software, or modify and sell derived works.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Strong
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Strong
Assessment confidence	High

Security considerations

API tokens must be treated as secrets—use Docker secrets or mounted files (CLOUDFLARE_API_TOKEN_FILE) rather than plaintext env vars. Default IP provider (Cloudflare Trace) is zero-log and avoids third-party IP tracking. Automatic rejection of Cloudflare anycast IPs prevents DNS poisoning from IP detection failures. No hardened runtime or network policy enforced by the tool itself; security relies on container orchestration and API token isolation. No CVE history or security audit data provided.

Alternatives to consider

ddclient

Perl-based DDNS client with broader DNS provider support (Route53, Azure, GoDaddy, DynDNS, etc.). Larger footprint (~5-10 MB) and higher resource usage; language choice (Perl) less favorable for minimal containers. Older, less actively maintained than cloudflare-ddns.

go-ddns (or other Go-based alternatives)

Go binaries are ~10-20 MB vs. 1.1 MB for Rust. Easier to find hosted versions. Cloudflare support varies by project. cloudflare-ddns is explicitly smaller and more memory-efficient than Go alternatives per README.

Cloudflare Workers + scheduled automation

Serverless alternative using Cloudflare's own platform for IP detection and DNS updates. Requires Cloudflare Workers subscription and JavaScript/TypeScript familiarity. No self-hosted infrastructure or Docker needed, but less transparent, harder to customize, and vendor lock-in to Cloudflare.

Software development agency

Build on cloudflare-ddns with DEV.co software developers

Deploy cloudflare-ddns in minutes with Docker. Requires a Cloudflare account, API token, and domains hosted on Cloudflare. Confirm GPLv3 license compatibility for your use case before production rollout.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

cloudflare-ai-web cloudprober tugtainer

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source DevOps DevOps & Infrastructure Automation Cloud Deployment & Infrastructure Talk to DEV.co

cloudflare-ddns FAQ

Can I use this with non-Cloudflare DNS providers?

No. This tool is purpose-built for Cloudflare API integration only. You will need a different DDNS client (e.g., ddclient, inadyn) for other providers like Route53, Azure DNS, or GoDaddy.

What API permissions do I need?

An API token with 'Edit DNS' capability. You do not need Admin or Account Owner access. Generate tokens in Cloudflare Profile (dash.cloudflare.com/profile/api-tokens) with scope limited to your zones for least-privilege security.

Why does IPv6 detection require --network host?

IPv6 address detection via local interfaces requires direct access to the host's network stack. Docker's default bridge network does not expose link-local IPv6 addresses needed for accurate detection. IPv4-only setups can omit --network host.

Is GPLv3 a problem for my use case?

Internal use (running in your own infrastructure) is permitted. Distribution, sale, or proprietary integration of modified versions requires open-sourcing those changes or separate commercial licensing. If you only run the tool as-is without distribution, GPLv3 poses no restriction.

Software developers & web developers for hire

From first prototype to production, DEV.co delivers software development services around tools like cloudflare-ddns. Our software development agency staffs experienced software developers and web developers for custom software development, web development, integrations, and ongoing support across open-source devops and beyond.

Ready to automate your home network DNS?

Talk to DEV.co Schedule a Consultation