cloudflare-ddns: a Rust DDNS updater whose IPv6 detection needs host networking
🦀 Rust based dynamic DNS (DDNS) updater for Cloudflare
At a glance
- What is it?
- cloudflare-ddns updates Cloudflare DNS records from environment variables, ships a ~1.1 MB static image, and protects records from two different kinds of detection failure. Its sharpest edges are documented rather than hidden: host networking is required for IPv6, Cloudflare anycast addresses are rejected on every cycle, and one failure mode still deletes records when DELETE_ON_FAILURE is set.
- Who is it for?
- cloudflare-ddns suits a self-hoster who already has a Cloudflare zone and an Edit DNS token and wants a container under 2 MB that will not quietly repoint a record at the wrong address. It does not suit someone who needs a hosted DDNS service, an IPv6 address on a host where Docker cannot use host networking, or a guarantee that records survive an outage, since DELETE_ON_FAILURE still removes them when a provider definitively reports no address of a family.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 6 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 13, 2026, and from our analysis. They are not legal advice.
Star history
- timothymiller/cloudflare-ddns4,561 ★ · +54
| Repository | 2026-09-13 | 2026-11-13 |
|---|---|---|
| timothymiller/cloudflare-ddns | 4.5k | 4.6k |
54 Stars in the last 61 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
--network host is mandatory for IPv6, and the workaround gives up IPv6
The quick start is one container run, and one flag in it is not decoration:
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:2.3.1Host networking is required to detect IPv6 addresses, and the documented alternative for an IPv4-only setup is to drop the flag and set IP6_PROVIDER=none. The consequence is that the choice is not between two equally good configurations. On any host where host networking is unavailable or unwelcome, the IPv6 half of this dual-stack updater simply is not available, and IP6_PROVIDER=none is the sanctioned way to admit that. With the defaults in place the container detects your public IP and updates the records for your domains every 5 minutes.
Two failure kinds, and only the second one can delete your records
The detection failure behavior is the most carefully argued part of this documentation, because it separates two cases that look identical from outside. A transient failure is a network provider erroring, or every detected IP being rejected as a Cloudflare address, and the real IP is simply unknown. In that case the update is skipped and existing DNS records and WAF list items are preserved regardless of DELETE_ON_FAILURE, and if one address family fails, WAF list updates are skipped entirely so the failed family's addresses are not stripped from the list. A definitive absence, the second case, is the only path where DELETE_ON_FAILURE can act. The consequence is that one setting behaves differently depending on why detection failed: when a deterministic provider such as none, literal:, local, local.iface: or local.iface.stable: reports no address of a family, the managed records of that family are deleted only with DELETE_ON_FAILURE=true.
Cloudflare's IP ranges are fetched every cycle, and a failed fetch stops updates
The default provider for IPv6 is cloudflare.trace, which reads Cloudflare's own /cdn-cgi/trace endpoint, and that design creates a specific hazard the project then guards against. Some IP detection providers occasionally return a Cloudflare anycast IP instead of your real public address, at which point your DNS record points at Cloudflare infrastructure. The guard is REJECT_CLOUDFLARE_IPS, default true: detected addresses inside Cloudflare's published ranges are discarded with a warning. The ranges are fetched on the first cycle and cached for 24 hours; if a refresh fails, the cached copy is kept, and only if they have never been fetched successfully is the cycle skipped rather than risk writing a Cloudflare IP. The consequence is that setting the variable to false removes the only thing standing between a bad detection and a broken record.
@once constrains two other variables at the same time
Scheduling is a single variable with a small set of formats: @every 5m, @every 1h, @every 30s, and @once, with @every 5m as the default. The remaining three scheduling variables decide what happens at the edges. By default the first update runs at startup rather than waiting out the first interval. DELETE_ON_STOP defaults to false, and DELETE_ON_FAILURE defaults to false. The @once format is the interesting case: with UPDATE_CRON=@once, the process exits with code 1 if the update failed, so cron jobs and systemd can detect it.
The image entrypoint passes --repeat, which the documentation never names
The release stage of the Dockerfile starts from scratch:
FROM scratch AS releaseThere is no shell in that image and no package manager, and the release image ships the CA bundle from the certs stage, while the binary is compressed with upx after a musl build. The Rust side matches that goal, since the release profile is tuned for size:
[profile.release]
opt-level = "z"
lto = true
codegen-units = 1
strip = true
panic = "abort"The consequence for anyone operating this is that debugging inside the container means running the binary outside it.
Configuration is all environment variables, yet a JSON example also ships
The README states that everything is configured with environment variables, and the authentication table makes that concrete with two mutually alternative ways to supply the token: CLOUDFLARE_API_TOKEN directly, or CLOUDFLARE_API_TOKEN_FILE pointing at a file. The token needs Zone › DNS › Edit and Zone › Zone › Read, created under My Profile › API Tokens in the Cloudflare dashboard. Domain selection is three variables, with DOMAINS covering both families and IP4_DOMAINS and IP6_DOMAINS covering one each, and at least one of DOMAINS, IP4_DOMAINS, IP6_DOMAINS, or WAF_LISTS must be set or the container has nothing to do. Wildcards such as *.example.com are supported. The consequence is that the repository also carries an env-example file and a config-example.json, and the README documents a legacy config.json mode that the program falls back to when environment-variable mode is not selected.
failure-safe delete shipped in a patch, and the docs are three loose files
The release titles record what was being corrected. v2.2.0, from 2026-07-21, adds Zulip notifications, safer failure handling, and a Helm chart. Since then, v2.3.0 from 2026-10-11 brought multi-interface support, reliability fixes and a docs overhaul, and v2.3.1 from 2026-10-28 distrusts compromised eMudhra CAs. The tree matches the release titles and adds deployment options: a charts/ directory for that Helm chart, plus k8s/, systemd/, docker/, and scripts/ for the other ways to run it, a CHANGELOG.md and a docs/ directory at the root, and SECURITY.md and CODE_OF_CONDUCT.md alongside a GPL-3.0 LICENSE. The Cargo manifest is at version 2.3.1 on edition 2021, matching the newest tag.
Editorial conclusion
cloudflare-ddns suits a self-hoster who already has a Cloudflare zone and an Edit DNS token and wants a container under 2 MB that will not quietly repoint a record at the wrong address. It does not suit someone who needs a hosted DDNS service, an IPv6 address on a host where Docker cannot use host networking, or a guarantee that records survive an outage, since DELETE_ON_FAILURE still removes them when a provider definitively reports no address of a family. Before running it, confirm your host allows --network host or accept IPv4-only with IP6_PROVIDER=none, read the detection failure section to the end, and remember the image is GPL-3.0.
Frequently asked questions
what is cloudflare ddns
It is a dynamic DNS client for Cloudflare written in Rust, published as the timothyjmiller/cloudflare-ddns container. It detects your public IP and updates the DNS records for your domains, configured entirely through environment variables, and the project describes it as a ~1.1 MB static Docker image built from scratch that uses about 3.5 MB of RAM.
what does cloudflare ddns do
It updates Cloudflare DNS records to point at your current public IP on a schedule, with IPv4 and IPv6 configured independently, and it can also manage Cloudflare WAF IP lists. Around that it adds Shoutrrr-compatible notifications, Healthchecks.io and Uptime Kuma heartbeat monitoring, cron scheduling, dry-run mode, graceful shutdown with optional record cleanup, and a managed record regex.
how to install cloudflare ddns
Run the published container, which needs a Cloudflare API token with Zone › DNS › Edit and Zone › Zone › Read permissions and at least one of DOMAINS, IP4_DOMAINS, IP6_DOMAINS, or WAF_LISTS set. Pass --network host for IPv6 detection, or omit it and set IP6_PROVIDER=none for IPv4 only.
how to setup cloudflare ddns
Set the token, then choose your detection providers: IP4_PROVIDER and IP6_PROVIDER both default to cloudflare.trace, with local, local.iface, url, literal, and none also available. REJECT_CLOUDFLARE_IPS defaults to true and UPDATE_CRON defaults to @every 5m.
how to use cloudflare ddns
Once the variables are in place the container detects your public IP and updates the records for your domains every 5 minutes, and the same run sends notifications and heartbeat pings. Dry-run mode previews changes without modifying DNS records, which is the documented way to see what a set of variables would do first.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/timothymiller-cloudflare-ddns)Star history chart for your README
[](https://hysenlabs.com/projects/timothymiller-cloudflare-ddns)Was this useful?