🌟 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.
<details><summary>✍️ You can verify the Docker images were built from this repository using the cosign tool (click to expand)</summary>
```
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.
<details><summary>📚 The updater uses only established open-source Go libraries (click to expand)</summary>
- 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.
</details>

⛷️ Quick Start

(Click to expand the following items.)

<details><summary>🐋 Directly run the Docker image.</summary>

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

</details> <details><summary>🧬 Directly run the updater from its source.</summary>

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

</details>

🐋 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.)

<details> <summary>🔑 <code>CF_API_TOKEN</code> is your Cloudflare API token</summary>

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!

</details> <details> <summary>📍 <code>DOMAINS</code> is the list of domains to update</summary>

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.

</details> <details> <summary>🚨 Remove <code>PROXIED=true</code> if you are not running a web server</summary>

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.

</details> <details> <summary>📴 Add <code>IP6_PROVIDER=none</code> if you want to disable IPv6 completely</summary>

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.

</details> <details> <summary>📡 Expand this if you want IPv6 without bypassing network isolation (without <code>network_mode: host</code>)</summary>

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.

</details> <details> <summary>🛡️ Change <code>user: "1000:1000"</code> to the user and group IDs you want to use</summary>

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.

</details>

🚀 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.)

<details> <summary>😠 I simulated an IP address change by editing the DNS records, but the updater never picked it up!</summary>

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.

</details> <details> <summary>😠 Why did the updater detect a public IP address different from the WAN IP address on my router?</summary>

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.

</details>

🎛️ Further Customization

⚙️ All Settings

(Click to expand the following items.)

<details> <summary>🔑 The Cloudflare API token</summary>

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

</details> <details> <summary>📍 DNS domains to update</summary>

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)

<details> <summary>📍 At least one of <code>DOMAINS</code>, <code>IP4/6_DOMAINS</code>, and <code>WAF_LISTS</code> must be non-empty.</summary>
At least something should be listed in DOMAINS, IP4_DOMAINS, IP6_DOMAINS, or WAF_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 both IP4_DOMAINS and IP6_DOMAINS, which is equivalent to listing it in DOMAINS. Internationalized domain names are supported using the non-transitional processing fully compatible with IDNA2008. See this useful FAQ on internationalized domain names.
</details>

<details> <summary>🃏 What are wildcard domains?</summary>
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.
</details>

</details> <details> <summary>🔍 IP address providers</summary>

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