You need the Go tool to run the updater from its source.

CLOUDFLARE_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

The value of CLOUDFLARE_API_TOKEN should be an API token (not an API key), which can be obtained from the API Tokens page. Use the Edit zone DNS template to create a token. The less secure API key authentication is deliberately not supported.

There is an optional feature (available since version 1.14.0) that lets you maintain a WAF list of detected IP addresses. To use this feature, edit the token and grant it the Account - Account Filter Lists - Edit permission. If you only need to update WAF lists, not DNS records, you can remove the Zone - DNS - Edit permission. Refer to the detailed documentation below for information on updating WAF lists.

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 share the same DNS zone---the updater will take care of the DNS zones behind the scene.

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.

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 seeing the detection errors), add IP6_PROVIDER=none.

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. Do use newer versions of Docker that come with much better IPv6 support!

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.

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:

1. A change of your actual IP address (a real change), or
2. 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.

The updater does not itself add timestamps because all major systems already timestamp everything:

• If you are using Docker Compose, Kubernetes, or Docker directly, add the option --timestamps when viewing the logs.
• If you are using Portainer, enable “Show timestamp” when viewing the logs.

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.

While the instructions for Kubernetes were removed due to high maintenance, you can still generate Kubernetes configurations from the provided Docker Compose template using a conversion tool like Kompose. Please note that only recent versions of Kompose support the user: "UID:GID" attribute with GID. (For more information, see my pull request that adds this feature to Kompose.)

Note that a simple Kubernetes Deployment will suffice here. Since there’s no inbound network traffic, a Kubernetes Service isn’t required.

Certain Docker installations may have issues with the no-new-privileges security option. If you cannot run Docker images with this option (including this updater), removing it might be necessary. This will slightly compromise security, but it’s better than not running the updater at all. If only this updater is affected, please report this issue on GitHub.

We have received reports that the default IP provider, cloudflare.trace, has recently begun returning an "error code: 1034." The current theory is that Cloudflare’s servers may be experiencing internal problems. We are tracking this issue at GitHub Issue 985. If IP detection fails, the updater will simply retry later. You can also switch to a different IP provider.

Starting with version 1.15.0, the updater supports environment variables that begin with CLOUDFLARE_*. Multiple environment variables can be used at the same time, provided they all specify the same token.

🚂 Cloudflare is updating its tools to use environment variables starting with CLOUDFLARE_* instead of CF_*. It is recommended to align your setting to align with this new convention. However, the updater will fully support both CLOUDFLARE_* and CF_* environment variables until version 2.0.0.

🔑 To update DNS records, the updater needs the Zone - DNS - Edit permission.

🔑 To manipulate WAF lists, the updater needs the Account - Account Filter Lists - Edit permission.

You need to specify at least one thing in DOMAINS, IP4_DOMAINS, IP6_DOMAINS, or 🧪 WAF_LISTS (since version 1.14.0) for the updater to update.

🃏🤖 Wildcard domains (*.example.org) represent all subdomains that would not exist otherwise. Therefore, if you have another subdomain entry sub.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.

🌐🤖 Internationalized domain names are handled using the nontransitional processing (fully compatible with IDNA2008). At this point, all major browsers and whatnot have switched to the same nontransitional processing. See this useful FAQ on internationalized domain names.

🤖 Technical notes on WAF lists:

1. Cloudflare does not allow single IPv6 addresses in a WAF list, and thus the updater will use the smallest IP range allowed by Cloudflare that contains the detected IPv6 address.
2. The updater will delete IP addresses belonging to unmanaged IP families from the specified WAF lists (e.g., if you disable IPv6 with IP6_PROVIDER=none, then existing IPv6 addresses or IPv6 ranges in the lists will be deleted). The idea is that the list should contain only detected IP addresses.

👉 The option IP4_PROVIDER governs A-type DNS records and IPv4 addresses in WAF lists, while the option IP6_PROVIDER governs AAAA-type DNS records and IPv6 addresses in WAF lists. The two options act independently of each other. You can specify different address providers for IPv4 and IPv6.

👉 The updater will preserve existing parameters (TTL, proxy states, DNS record comments, etc.). Only when it creates new DNS records and new WAF lists, the following settings will apply. To change existing parameters, you can go to your Cloudflare Dashboard and change them directly. If you think you have a use case where the updater should actively overwrite existing parameters in addition to IP addresses, please let me know. 🐞🧪 KNOWN ISSUE: comments of stale WAF list items (not WAF lists themselves) will not be kept because the Cloudflare API does not provide an easy way to update list items. The comments will be lost when the updater deletes stale list items and create new ones.

🤖 For advanced users: the PROXIED can be a boolean expression involving domains! This allows you to enable Cloudflare proxying for some domains but not the others. Here are some example expressions:

• PROXIED=is(example.org): proxy only the domain example.org
• PROXIED=is(example1.org) || sub(example2.org): proxy only the domain example1.org and subdomains of example2.org
• PROXIED=!is(example.org): proxy every managed domain except for example.org
• PROXIED=is(example1.org) || is(example2.org) || is(example3.org): proxy only the domains example1.org, example2.org, and example3.org

A boolean expression must be one of the following forms (all whitespace is ignored):

Syntax	Meaning
Any string accepted by strconv.ParseBool, such as true, false, 0, or 1	Logical truth or falsehood
is(d)	Matching the domain d. Note that is(*.a) only matches the wildcard domain *.a; use sub(a) to match all subdomains of a (including *.a).
sub(d)	Matching subdomains of d, such as a.d, b.c.d, and *.d. It does not match the domain d itself.
! e	Logical negation of the boolean expression e
e1 || e2	Logical disjunction of the boolean expressions e1 and e2
e1 && e2	Logical conjunction of the boolean expressions e1 and e2

One can use parentheses to group expressions, such as !(is(a) && (is(b) || is(c))). For convenience, the parser also accepts these short forms:

Short Form	Equivalent Full Form
is(d1, d2, ..., dn)	is(d1) || is(d2) || ... || is(dn)
sub(d1, d2, ..., dn)	sub(d1) || sub(d2) || ... || sub(dn)

For example, these two settings are equivalent:

• PROXIED=is(example1.org) || is(example2.org) || is(example3.org)
• PROXIED=is(example1.org,example2.org,example3.org)

💡 If your network doesn’t support IPv6, set IP6_PROVIDER=none to disable IPv6. This will prevent the updater from reporting failures in detecting IPv6 addresses to monitoring services. Similarly, set IP4_PROVIDER=none if your network doesn’t support IPv4.

⚠️ oznu/cloudflare-ddns relies on the insecure DNS protocol to obtain public IP addresses; a malicious hacker could more easily forge DNS responses and trick it into updating your domain with any IP address. In comparison, we use only verified responses from Cloudflare, which makes the attack much more difficult. See the design document for more information on security.

📜 Some historical notes: This updater was originally written as a Go clone of the Python program timothymiller/cloudflare-ddns because the Python program always purged unmanaged DNS records back then and it was not configurable via environment variables. There were feature requests to address these issues but the author timothymiller seemed to ignore them; I thus made my Go clone after unsuccessful communications. Understandably, timothymiller did not seem happy with my cloning and my other critical comments towards other aspects of the Python updater. Eventually, an option purgeUnknownRecords was added to the Python program to disable the unwanted purging, and it became configurable via environment variables, but my Go clone already went on its way. I believe my Go clone is now a much better choice, but my opinions are biased and you should check the technical details by yourself. 😉