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

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 ./cmd/*.go

👉 For non-Linux operating systems, please use Docker images instead.

The easiest way to enable IPv6 is to use network_mode: host so that the updater can access the host IPv6 network directly. If you wish to keep the updater isolated from the host network, check out the official documentation on IPv6 and this GitHub issue about IPv6. If your host OS is Linux, here’s the tl;dr:

1. Use network_mode: bridge instead of network_mode: host.
2. Edit or create /etc/docker/daemon.json with the following content:

   {
     "ipv6": true,
     "fixed-cidr-v6": "fd00::/8",
     "experimental": true,
     "ip6tables": true
   }
   

3. Restart the Docker daemon (if you are using systemd):

   systemctl restart docker.service
   

Docker’s default restart policies should prevent excessive logging when there are configuration errors.

Change 1000 to the user or group IDs you wish to use to run the updater. The setting no-new-privileges:true provides additional protection, especially when you run the container as a non-superuser. The updater itself will read PUID and PGID and attempt to drop all those privileges as much as possible.

The setting PROXIED=true instructs Cloudflare to cache webpages on your machine and hide your actual IP addresses. If you wish to bypass that and expose your actual IP addresses, simply remove PROXIED=true. (The default value of PROXIED is false.)

The value of CF_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 and copy a token into the environment file. ⚠️ The less secure API key authentication is deliberately not supported.

The value of DOMAINS should be a list of fully qualified domain names 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.

Kubernetes’s default restart policies should prevent excessive logging when there are configuration errors.

Kubernetes comes with built-in support to drop superuser privileges. The updater itself will also attempt to drop all of them.

The support of IPv6 in Kubernetes has been improving, but a working setup still takes effort. Since Kubernetes 1.21+, the IPv4/IPv6 dual stack is enabled by default, but a setup which allows IPv6 egress traffic (e.g., to reach Cloudflare servers to detect public IPv6 addresses) still requires deep understanding of Kubernetes and is beyond this simple guide. The popular tool minicube, which implements a simple local Kubernetes cluster, unfortunately does not support IPv6 yet. Until there is an easy way to enable IPv6 in Kubernetes, the template here will have IPv6 disabled.

If you manage to enable IPv6, congratulations. Feel free to remove IP6_PROVIDER: "none" to detect and update both A and AAAA records. There is almost no danger in enabling IPv6 even when the IPv6 setup is not working. In the worst case, the updater will remove all AAAA records associated with the domains in DOMAINS and IP6_DOMAINS because those records will appear to be “stale.” The deleted records will be recreated once the updater correctly detects the IPv6 addresses.

The setting PROXIED: "true" instructs Cloudflare to cache webpages on your machine and hide your actual IP addresses. If you wish to bypass that and expose your actual IP addresses, simply remove PROXIED: "true". (The default value of PROXIED is false.)

The value of CF_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 and copy a token into the environment file. ⚠️ The less secure API key authentication is deliberately not supported.

The value of DOMAINS should be a list of fully qualified domain names 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.

In most cases, CF_ACCOUNT_ID is not needed.

📍 At least one of DOMAINS and IP4/6_DOMAINS must be non-empty.

At least one domain should be listed in DOMAINS, IP4_DOMAINS, or IP6_DOMAINS. Otherwise, if all of them are empty, then the updater has nothing to do. It is fine to list the same domain in both IP4_DOMAINS and IP6_DOMAINS, which is equivalent to listing it in DOMAINS. Internationalized domain names are supported using the non-transitional processing that is fully compatible with IDNA2008.

📜 Available providers for IP4_PROVIDER and IP6_PROVIDER:

• cloudflare.doh
  Get the public IP address by querying whoami.cloudflare. against Cloudflare via DNS-over-HTTPS and update DNS records accordingly.
• cloudflare.trace
  Get the public IP address by parsing the Cloudflare debugging page and update DNS records accordingly.
• ipify
  Get the public IP address via ipify’s public API and update DNS records accordingly.
• local
  Get the address via local network interfaces and update DNS records accordingly. When multiple local network interfaces or in general multiple IP addresses are present, the updater will use the address that would have been used for outbound UDP connections to Cloudflare servers. ⚠️ You need access to the host network (such as network_mode: host in Docker Compose or hostNetwork: true in Kubernetes) for this policy, for otherwise the updater will detect the addresses inside the bridge network in Docker or the default namespaces in Kubernetes instead of those in the host network.
• none
  Stop the DNS updating completely. Existing DNS records will not be removed.

The option IP4_PROVIDER is governing IPv4 addresses and A-type records, while the option IP6_PROVIDER is governing IPv6 addresses and AAAA-type records. The two options act independently of each other.

🃏 What are wildcard domains?

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.

⚠️ The update schedule does not take the time to update records into consideration. For example, if the schedule is “for every 5 minutes”, and if the updating itself takes 2 minutes, then the actual interval between adjacent updates is 3 minutes, not 5 minutes.

👉 The updater will preserve existing proxy and TTL settings until it has to create new DNS records (or recreate deleted ones). Only when it creates DNS records, the above settings will apply. To change existing proxy and TTL settings now, 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 proxy and TTL settings in addition to IP addresses, please let me know. It is not hard to implement optional overwriting.

🧪 Experimental per-domain proxy settings (subject to changes):

The PROXIED can be a boolean expression. Here are some examples:

• 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 has one of the following forms (all whitespace is ignored):

• A boolean value accepted by strconv.ParseBool, such as t as true or FALSE as false.
• is(d) which matches 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) which matches subdomains of d, such as a.d and b.d. It does not match the domain d itself.
• ! e where e is a boolean expression, representing logical negation of e.
• e1 || e2 where e1 and e2 are boolean expressions, representing logical disjunction of e1 and e2.
• e1 && e2 where e1 and e2 are boolean expressions, representing logical conjunction of e1 and e2.

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

• is(d1, d2, ..., dn) is is(d1) || is(d2) || ... || is(dn)
• sub(d1, d2, ..., dn) is sub(d1) || sub(d2) || ... || sub(dn)

For example, these two settings are equivalent:

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

👉 The updater will also try to drop supplementary group IDs.

For HEALTHCHECKS, the updater accepts any URL that follows the same notification protocol.

⚠️ oznu/cloudflare-ddns relies on unverified DNS responses to obtain public IP addresses; a malicious hacker could potentially manipulate or forge DNS responses and trick it into updating your domain with any IP address. In comparison, we use only verified responses from Cloudflare or ipify.