🌟 Cloudflare DDNS
A feature-rich and robust Cloudflare DDNS updater with a small footprint. The program will detect your machine's public IP addresses and update DNS records using the Cloudflare API.
📜 Highlights
⚡ Efficiency
- 🤏 The Docker image takes less than 5 MB after compression.
- 🔁 The Go runtime re-uses existing HTTP connections.
- 🗃️ Cloudflare API responses are cached to reduce the API usage.
💯 Complete Support of Domain Names
- 😌 You can simply list domains (e.g.,
www.a.org, hello.io
) without knowing their DNS zones. - 🌍 Internationalized domain names (e.g.,
🐱.example.org
and日本。co。jp
) are fully supported. - 🃏 Wildcard domains (e.g.,
*.example.org
) are also supported. - 🕹️ You can toggle IPv4 (
A
records) and IPv6 (AAAA
records) for each domain.
🌥️ Enjoy Cloudflare-specific Features
- 😶🌫️ You can toggle Cloudflare proxying for each domain.
- 📝 You can set DNS record comments (and record tags very soon).
- 📜 The updater can manage a custom list of detected IP addresses for you to use in Web Application Firewalls (WAF) rules.
🕵️ Privacy
By default, public IP addresses are obtained via Cloudflare debugging page. This minimizes the impact on privacy because we are already using the Cloudflare API to update DNS records. Moreover, if Cloudflare servers are not reachable, chances are you cannot update DNS records anyways.
👁️ Notification
- 🩺 The updater can work with Healthchecks or Uptime Kuma so that you receive notifications when it fails to update IP addresses.
- 📣 The updater can also actively send you notifications via any service supported by the shoutrrr library, including emails, major notification services, major messaging platforms, and generic webhooks.
🛡️ Security
-
🛡️ The updater uses only HTTPS or DNS over HTTPS to detect IP addresses. This makes it harder for someone else to trick the updater into updating your DNS records with wrong IP addresses. See the Security Model for more information.
-
✍️ You can verify the Docker images were built from this repository using the cosign tool (click to expand)
cosign verify favonia/cloudflare-ddns:latest \ --certificate-identity-regexp https://github.com/favonia/cloudflare-ddns/ \ --certificate-oidc-issuer https://token.actions.githubusercontent.com
Note: this only proves that a Docker image is from this repository. It cannot prevent malicious code if someone hacks into GitHub or this repository.
-
📚 The updater uses only established open-source Go libraries (click to expand)
- cloudflare-go:
The official Go binding of Cloudflare API v4. - cron:
Parsing of Cron expressions. - go-retryablehttp:
HTTP clients with automatic retries and exponential backoff. - go-querystring:
A library to construct URL query parameters. - shoutrrr:
A notification library for sending general updates. - ttlcache:
In-memory cache to hold Cloudflare API responses. - mock (for testing only):
A comprehensive, semi-official framework for mocking. - testify (for testing only):
A comprehensive tool set for testing Go programs.
- cloudflare-go:
⛷️ Quick Start
(Click to expand the following items.)
🐋 Directly run the Docker image.
docker run \
--network host \
-e CF_API_TOKEN=YOUR-CLOUDFLARE-API-TOKEN \
-e DOMAINS=example.org,www.example.org,example.io \
-e PROXIED=true \
favonia/cloudflare-ddns:latest
🧬 Directly run the updater from its source.
You need the Go tool to run the updater from its source.
CF_API_TOKEN=YOUR-CLOUDFLARE-API-TOKEN \
DOMAINS=example.org,www.example.org,example.io \
PROXIED=true \
go run github.com/favonia/cloudflare-ddns/cmd/ddns@latest
🐋 Deployment with Docker Compose
📦 Step 1: Updating the Compose File
Incorporate the following fragment into the compose file (typically docker-compose.yml
or docker-compose.yaml
). The template may look a bit scary, but only because it includes various optional flags for extra security protection.
services:
cloudflare-ddns:
image: favonia/cloudflare-ddns:latest
# Choose the appropriate tag based on your need:
# - "latest" for the latest stable version (which could become 2.x.y
# in the future and break things)
# - "1" for the latest stable version whose major version is 1
# - "1.x.y" to pin the specific version 1.x.y
network_mode: host
# This bypasses network isolation and makes IPv6 easier (optional; see below)
restart: always
# Restart the updater after reboot
user: "1000:1000"
# Run the updater with specific user and group IDs (in that order).
# You can change the two numbers based on your need.
read_only: true
# Make the container filesystem read-only (optional but recommended)
cap_drop: [all]
# Drop all Linux capabilities (optional but recommended)
security_opt: [no-new-privileges:true]
# Another protection to restrict superuser privileges (optional but recommended)
environment:
- CF_API_TOKEN=YOUR-CLOUDFLARE-API-TOKEN
# Your Cloudflare API token
- DOMAINS=example.org,www.example.org,example.io
# Your domains (separated by commas)
- PROXIED=true
# Tell Cloudflare to cache webpages and hide your IP (optional)
(Click to expand the following important tips.)
🔑 CF_API_TOKEN
is your Cloudflare API token
The value of CF_API_TOKEN
should be an API token (not an API key), which can be obtained from the API Tokens page. (The less secure API key authentication is deliberately not supported.)
- To update only DNS records, use the Edit zone DNS template to create a token.
- To update only WAF lists, choose Create Custom Token and add the Accounts - Account Filter Lists - Write permission to create a token.
- To update DNS records and WAF lists, use the Edit zone DNS template and add the Accounts - Account Filter Lists - Write permission to create a token.
You can also grant new permissions to existing tokens at any time!
📍 DOMAINS
is the list of domains to update
The value of DOMAINS
should be a list of fully qualified domain names (FQDNs) separated by commas. For example, DOMAINS=example.org,www.example.org,example.io
instructs the updater to manage the domains example.org
, www.example.org
, and example.io
. These domains do not have to be in the same zone---the updater will identify their zones automatically.
🚨 Remove PROXIED=true
if you are not running a web server
The setting PROXIED=true
instructs Cloudflare to cache webpages and hide your IP addresses. If you wish to bypass that and expose your actual IP addresses, remove PROXIED=true
. If your traffic is not HTTP(S), then Cloudflare cannot proxy it and you should probably turn off the proxying by removing PROXIED=true
. The default value of PROXIED
is false
.
📴 Add IP6_PROVIDER=none
if you want to disable IPv6 completely
The updater, by default, will attempt to update DNS records for both IPv4 and IPv6, and there is no harm in leaving the automatic detection on even if your network does not work for one of them. However, if you want to disable IPv6 entirely (perhaps to avoid all the detection errors), add the setting IP6_PROVIDER=none
.
📡 Expand this if you want IPv6 without bypassing network isolation (without network_mode: host
)
The easiest way to enable IPv6 is to use network_mode: host
so that the updater can access the host IPv6 network directly. This has the downside of bypassing the network isolation. If you wish to keep the updater isolated from the host network, remove network_mode: host
and follow the steps in the official Docker documentation to enable IPv6. Use newer versions of Docker that come with (much) better IPv6 support.
🛡️ Change user: "1000:1000"
to the user and group IDs you want to use
Change 1000:1000
to USER:GROUP
for the USER
and GROUP
IDs you wish to use to run the updater. The settings cap_drop
, read_only
, and no-new-privileges
in the template provide additional protection, especially when you run the container as a non-superuser.
🚀 Step 2: Building the Container
docker-compose pull cloudflare-ddns
docker-compose up --detach --build cloudflare-ddns
❓ Frequently Asked Questions
(Click to expand the following items.)
😠 I simulated an IP address change by editing the DNS records, but the updater never picked it up!
Please rest assured that the updater is working as expected. It will update the DNS records immediately for a real IP change. Here is a detailed explanation. There are two causes of an IP mismatch:
- A change of your actual IP address (a real change), or
- A change of the IP address in the DNS records (a simulated change).
The updater assumes no one will actively change the DNS records. In other words, it assumes simulated changes will not happen. It thus caches the DNS records and cannot detect your simulated changes. However, when your actual IP address changes, the updater will immediately update the DNS records. Also, the updater will eventually check the DNS records and detect simulated changes after CACHE_EXPIRATION
(six hours by default) has passed.
If you really wish to test the updater with simulated IP changes in the DNS records, you can set CACHE_EXPIRATION=1ns
(all cache expiring in one nanosecond), effectively disabling the caching. However, it is recommended to keep the default value (six hours) to reduce your network traffic.
😠 Why did the updater detect a public IP address different from the WAN IP address on my router?
Is your “public” IP address on your router between 100.64.0.0
and 100.127.255.255
? If so, you are within your ISP’s CGNAT (Carrier-grade NAT). In practice, there is no way for DDNS to work with CGNAT, because your ISP does not give you a real public IP address, nor does it allow you to forward IP packages to your router using cool protocols such as Port Control Protocol. You have to give up DDNS or switch to another ISP. You may consider other services such as Cloudflare Tunnel that can work around CGNAT.
🎛️ Further Customization
⚙️ All Settings
(Click to expand the following items.)
🔑 The Cloudflare API token
Name | Valid Values | Meaning | Required? | Default Value |
---|---|---|---|---|
CF_API_TOKEN | Cloudflare API tokens | The token to access the Cloudflare API | Exactly one of CF_API_TOKEN and CF_API_TOKEN_FILE should be set | N/A |
CF_API_TOKEN_FILE | Paths to files containing Cloudflare API tokens | A file that contains the token to access the Cloudflare API | Exactly one of CF_API_TOKEN and CF_API_TOKEN_FILE should be set | N/A |
📍 DNS domains to update
Name | Valid Values | Meaning | Required? | Default Value |
---|---|---|---|---|
DOMAINS | Comma-separated fully qualified domain names or wildcard domain names | The domains the updater should manage for both A and AAAA records | (See below) | (empty list) |
IP4_DOMAINS | Comma-separated fully qualified domain names or wildcard domain names | The domains the updater should manage for A records | (See below) | (empty list) |
IP6_DOMAINS | Comma-separated fully qualified domain names or wildcard domain names | The domains the updater should manage for AAAA records | (See below) | (empty list) |
📍 At least one of
DOMAINS
,IP4/6_DOMAINS
, andWAF_LISTS
must be non-empty.At least something should be listed in
DOMAINS
,IP4_DOMAINS
,IP6_DOMAINS
, orWAF_LISTS
(for WAF lists, see below). Otherwise, if all of them are empty, then the updater has nothing to do. It is fine to list the same domain in bothIP4_DOMAINS
andIP6_DOMAINS
, which is equivalent to listing it inDOMAINS
. Internationalized domain names are supported using the non-transitional processing fully compatible with IDNA2008. See this useful FAQ on internationalized domain names.
🃏 What are wildcard domains?
Wildcard domains (
*.example.org
) represent all subdomains that would not exist otherwise. Therefore, if you have another subdomain entrysub.example.org
, the wildcard domain is independent of it, because it only represents the other subdomains which do not have their own entries. Also, you can only have one layer of*
---*.*.example.org
would not work.
🔍 IP address providers
Name | Valid Values | Meaning | Required? | Default Value |
---|---|---|---|---|
IP4_PROVIDER | cloudflare.doh , cloudflare.trace , local , url:URL , or none | How to detect IPv4 addresses, or none to disable IPv4 (see below) | No | cloudflare.trace |
IP6_PROVIDER | cloudflare.doh , cloudflare.trace , local , url:URL , or none | How |