favonia/cloudflare-ddns

# 🌟 Cloudflare DDNS [](https://github.com/favonia/cloudflare-ddns) [](https://app.codecov.io/gh/favonia/cloudflare-ddns) [](https://hub.docker.com/r/favonia/cloudflare-ddns) [](https://www.bestpractices.dev/en/projects/6680/passing) [](https://securityscorecards.dev/viewer/?uri=github.com/favonia/cloudflare-ddns) A feature-rich and robust Cloudflare DDNS updater with a small Docker image. It detects your machine’s public IP addresses and updates DNS records through the Cloudflare API. ## ✨ Highlights ### 🌥️ Cloudflare-specific Features - 📝 The updater preserves existing [Cloudflare proxy statuses](https://developers.cloudflare.com/dns/proxy-status/), [TTLs](https://developers.cloudflare.com/dns/manage-dns-records/reference/ttl/), and [comments](https://developers.cloudflare.com/dns/manage-dns-records/reference/record-attributes/) for managed DNS records. You can set fallback values for cases where the updater needs to supply them. - 📜 The updater can maintain [lists](https://developers.cloudflare.com/waf/tools/lists/custom-lists/) of detected IP addresses. These lists can then be referenced in any Cloudflare product that uses [Cloudflare’s Rules language](https://developers.cloudflare.com/ruleset-engine/), such as [Cloudflare Web Application Firewall (WAF)](https://developers.cloudflare.com/waf/) and [Cloudflare Rules](https://developers.cloudflare.com/rules/). (We call the lists “WAF lists”, but their use is not limited to Cloudflare WAF.) ### 🔔 Integration with Notification Services - 🩺 The updater can report to [Healthchecks](https://healthchecks.io) or [Uptime Kuma](https://uptime.kuma.pet) so that you receive notifications when it fails to update IP addresses. - 📣 The updater can also actively update you via any service supported by the [shoutrrr library](https://containrrr.dev/shoutrrr/), including emails, major notification services, major messaging platforms, and generic webhooks. ### 🧱 Reliability - The code is extensively tested. - 🔬 Compatibility with the Cloudflare API is verified periodically with [dedicated scripts](scripts/README.markdown). - 🧰 The updater is designed to recover from transient network failures. ### 🔒 Security and Privacy - 🙈 By default, public IP addresses are obtained via [Cloudflare’s debugging page](https://one.one.one.one/cdn-cgi/trace). This minimizes the impact on privacy because we are already using the Cloudflare API to update DNS records. - 🛡️ By default, the updater uses only HTTPS or [DNS over HTTPS](https://en.wikipedia.org/wiki/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](docs/designs/features/network-security-model.markdown) for more information. -

🔏 You can verify with cosign that the Docker images were built from this repository ^{click to expand}

cosign verify favonia/cloudflare-ddns:1 \ --certificate-identity-regexp https://github.com/favonia/cloudflare-ddns/ \ --certificate-oidc-issuer https://token.actions.githubusercontent.com This only proves that the Docker image is from this repository, assuming that no one hacks into GitHub or the repository. It does not prove that the code itself is secure.

### 🧭 Principled Design - 📚 The updater is guided by detailed and principled [design documents](./docs/designs/README.markdown). -

📦 The updater uses only a small set of established external Go packages ^{click to expand}

• cloudflare-go: official Go binding of Cloudflare API v4.
• cron: parsing of Cron expressions.
• go-retryablehttp: HTTP clients with retries and exponential backoff.
• go-querystring: library to construct URL query parameters.
• shoutrrr: notification library for sending general updates.
• ttlcache: in-memory cache to hold Cloudflare API responses.
• x/net: official Go supplementary packages for domain handling and low-level DNS support.
• x/text: official Go supplementary packages for locale-aware text handling.
• mock (for testing only): semi-official framework for mocking.
• testify (for testing only): tool set for testing Go programs.

### ⚡ Efficiency - The default Docker image stays small. - 🗃️ Cloudflare API responses are cached to reduce the API usage. ## 🚀 Quick Start

🐋 Directly run the Docker image ^{click to expand}

Create a Cloudflare API token from the [API Tokens page](https://dash.cloudflare.com/profile/api-tokens) with the **Zone - DNS - Edit** and **Account - Account Filter Lists - Edit** permissions. You can remove unneeded permissions based on your setup; see [Cloudflare API Tokens](#cloudflare-api-token) for details. docker run \ --network host \ -e CLOUDFLARE_API_TOKEN=YOUR-CLOUDFLARE-API-TOKEN \ -e DOMAINS=example.org,www.example.org,example.io \ -e PROXIED=true \ favonia/cloudflare-ddns:1 ⚠️ `PROXIED=true` does not change the proxy statuses of existing records. See [DNS and WAF Fallback Values](#dns-and-waf-fallback-values).

🧬 Directly run the updater from its source ^{click to expand}

Create a Cloudflare API token from the [API Tokens page](https://dash.cloudflare.com/profile/api-tokens) with the **Zone - DNS - Edit** and **Account - Account Filter Lists - Edit** permissions. You can remove unneeded permissions based on your setup; see [Cloudflare API Tokens](#cloudflare-api-token) for details. You need the [Go tool](https://go.dev/doc/install) 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 ⚠️ `PROXIED=true` does not change the proxy statuses of existing records. See [DNS and WAF Fallback Values](#dns-and-waf-fallback-values).

## 🐋 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 looks a bit scary only because it includes various optional flags for extra security protection. services: cloudflare-ddns: image: favonia/cloudflare-ddns:1 # Prefer "1" or "1.x.y" in production. # # - "1" tracks the latest stable release whose major version is 1 # - "1.x.y" pins one specific stable version # - "latest" moves to each new stable release and may pick up breaking # changes in a future major release, so it is not recommended in production # - "edge" tracks the latest unreleased development build network_mode: host # Optional. This bypasses network isolation and makes IPv6 easier. # See "Use IPv6 without sharing the host network". 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: - CLOUDFLARE_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 # Leaning toward using Cloudflare's proxy for these domains (optional) # Existing DNS records in Cloudflare keep their current proxy statuses

CLOUDFLARE_API_TOKEN should be a Cloudflare API token, not the older global API key used by some other tools. Create one from the API Tokens page, typically using the Edit zone DNS template. If you also use WAF lists, add the Account - Account Filter Lists - Edit permission.

The `user: "1000:1000"` line sets the user and group IDs that the container runs as, and you can change those two numbers to match your system. The `cap_drop`, `read_only`, and `no-new-privileges` lines add extra protection, especially when you run the container as a non-superuser.

📍 DOMAINS is the list of domains to update ^{click to expand}

The value of `DOMAINS` should be a list of [fully qualified domain names (FQDNs)](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) 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 scenes.

🚨 Remove PROXIED=true if you are not running a web server ^{click to expand}

Keep `PROXIED=true` when you want [Cloudflare’s proxy](https://developers.cloudflare.com/dns/proxy-status/) for the domains managed by this updater. Proxying lets Cloudflare cache webpages and hide your IP addresses. | If you want... | Do this | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Create new records that expose your real IP addresses | Remove `PROXIED=true` or change it to `PROXIED=false` | | Create new records for non-HTTP(S) traffic | Remove `PROXIED=true` or change it to `PROXIED=false`, because Cloudflare cannot proxy it | | Create new records whose HTTP(S) traffic is proxied | Keep `PROXIED=true` | | Change the proxy statuses of existing records | Change them manually on the [Cloudflare DNS Records page](https://dash.cloudflare.com/?to=/:account/:zone/dns/records) | The default value of `PROXIED` is `false`.

If you need a non-default Docker Compose deployment, see [Docker Compose Special Setups](#docker-compose-special-setups). ### 🚀 Step 2: Building and Running the Container docker-compose pull cloudflare-ddns docker-compose up --detach --build cloudflare-ddns The updater should now be running in the background. Check the logs with `docker-compose logs cloudflare-ddns` and confirm that it started correctly. ## 🧩 Docker Compose Special Setups These setups are additive changes on top of the basic Docker Compose template in [Step 1: Updating the Compose File](#docker-compose-template). Each setup shows a minimal delta. For the exact behavior of each environment variable, see [All Settings](#all-settings). ### ✅ Validation and Testing #### Test a new setup with explicit IPs Use this when you want to validate the updater without waiting for a real IP change. Point the updater at dedicated test domain names and feed it explicit test IPs: environment: - DOMAINS=ddns-test.example.org - IP4_PROVIDER=static:203.0.113.10 - IP6_PROVIDER=static:2001:db8::10 After the testing is done, switch `DOMAINS`, `IP4_PROVIDER`, and `IP6_PROVIDER` to your production values. ⚠️ `static:,,...` is an advanced provider that supplies a fixed set of IP addresses. It is useful for tests, debugging, and other setups where you want to feed a known address set into the updater, but it is not the normal long-running DDNS path. #### Test a new setup with changing IPs (available since version 1.16.0) Use this when you want to validate the updater with simulated IP changes by reading test addresses from local files. Create `ip4.txt` and `ip6.txt` with one IP address per line (blank lines and `#` comments are ignored). Then, point the updater at dedicated test domain names and feed it the file paths: environment: - DOMAINS=ddns-test.example.org - IP4_PROVIDER=file:/ip4.txt - IP6_PROVIDER=file:/ip6.txt volumes: - $PWD/ip4.txt:/ip4.txt - $PWD/ip6.txt:/ip6.txt After the updater creates or updates the expected records, change the addresses in `ip4.txt` or `ip6.txt` to simulate further IP changes. The updater should pick up new content and reconcile the DNS records. After testing is done, switch `DOMAINS`, `IP4_PROVIDER`, and `IP6_PROVIDER` to your production values and remove the test files and `volumes:` entries. #### Test how the updater reconciles manual DNS edits Use this when you want to test how the updater responds after DNS records are changed directly in Cloudflare. By default, the updater caches Cloudflare API responses to reduce network traffic. To make it fetch the latest DNS records every time, disable that cache: environment: - CACHE_EXPIRATION=1ns With `CACHE_EXPIRATION=1ns`, you can edit DNS records in Cloudflare and watch the updater reconcile them right away. `CACHE_EXPIRATION` affects cached Cloudflare API responses. It does not affect public IP detection. The updater still detects the current public IP addresses each time it runs. Restore the default `CACHE_EXPIRATION` afterward to avoid unnecessary network traffic. ### 🌐 Networking #### Run IPv4-only or IPv6-only Use this when your network supports only one IP family or when you want to stop seeing detection failures for the other one. environment: - IP6_PROVIDER=none Use `IP6_PROVIDER=none` to stop managing IPv6, or `IP4_PROVIDER=none` to stop managing IPv4. Existing managed DNS records of that IP family are preserved. 🧪 If you also use WAF lists, existing managed items of that IP family are preserved there too. #### Use IPv6 without sharing the host network services: cloudflare-ddns: # Remove this line: # network_mode: host #### Route through a specific host interface Use this when the updater runs in Docker and should route all outbound requests through a particular host network interface. This is useful when you want Cloudflare-based providers (`cloudflare.doh`, `cloudflare.dot`) or other IP detection websites (`url:`) to see the public IPs via a specific interface. One possible approach is to use [IPvlan network driver](https://docs.docker.com/engine/network/drivers/ipvlan/) to create a virtual network attached to that host interface, and then attach this updater to it. Add the following snippet to your Compose file where `` is the name of the host interface: networks: ddns: driver: ipvlan driver_opts: parent: ipvlan_mode: l2 ipam: config: - subnet: gateway: Replace ``, ``, and `` to match the host interface you want the container to use. - On the host, run `ip route show dev proto kernel` and use the subnet in CIDR notation as your ``, such as `192.168.1.0/24`. - On the host, run `ip route show default dev ` and use the `via` address as your ``, such as `192.168.1.1`. Then attach the service to that network instead of using `network_mode: host`: services: cloudflare-ddns: # This line replaces "network_mode: host" networks: [ddns] ⚠️ `ipvlan` does not use Docker’s usual bridge-network firewall rules, and the host is not directly reachable from the container on this network. Make sure your host firewall expects the new traffic. #### 🧪 Read addresses from one host interface Use this when you are already using `network_mode: host` and want the updater to read addresses from one specific host interface instead of choosing from all host interfaces. environment: - IP4_PROVIDER=local.iface:eth0 - IP6_PROVIDER=local.iface:eth0 If you want to change where outbound requests leave the container instead, see [Route through a specific host interface](#docker-interface-routing). 🧪 `local.iface:` is still experimental. ### 🔐 Cloudflare API Tokens #### Read the Cloudflare token from a Docker secret Use this when you do not want to put the token directly in the Compose file or `.env` file. Replace the inline token with a file-backed token: services: cloudflare-ddns: environment: - CLOUDFLARE_API_TOKEN_FILE=/run/secrets/cloudflare_api_token secrets: - cloudflare_api_token secrets: cloudflare_api_token: file: ./secrets/cloudflare_api_token.txt ⚠️ The token file must be readable by the user configured by `user: "UID:GID"`. ### 🧭 Resource Scope and Ownership #### 🧪 Update only WAF lists The updater can work without DNS records and manage only WAF lists. environment: - WAF_LISTS=0123456789abcdef0123456789abcdef/home-ips # Do not set DOMAINS, IP4_DOMAINS, or IP6_DOMAINS Use a Cloudflare API token with the **Account - Account Filter Lists - Edit** permission. ### 🤝 Multiple Instances Use this when multiple updater instances may overlap and each instance should manage only its own resources. The DNS setup and the WAF setup are independent: - If multiple instances share DNS domains, configure the DNS subsection. - If multiple instances share WAF lists, configure the WAF subsection. - If both apply, configure both subsections. #### Share DNS domains across updater instances Use this when multiple instances share DNS domains. This setup does not use WAF lists. Give each instance its own DNS record comment value and matching selector: 1. Set a unique `RECORD_COMMENT`. 2. Set `MANAGED_RECORDS_COMMENT_REGEX` to match that same DNS comment, typically with `^...$`. Example: - Instance A: `RECORD_COMMENT=managed-by-ddns-a`, `MANAGED_RECORDS_COMMENT_REGEX=^managed-by-ddns-a$` - Instance B: `RECORD_COMMENT=managed-by-ddns-b`, `MANAGED_RECORDS_COMMENT_REGEX=^managed-by-ddns-b$` #### Share WAF lists across updater instances Use this when multiple instances share WAF lists. This setup does not use the DNS settings in Share DNS domains across updater instances. Give each instance its own WAF list item comment and matching selector: 1. Set a unique `WAF_LIST_ITEM_COMMENT`. 2. Set `MANAGED_WAF_LIST_ITEMS_COMMENT_REGEX` to match that same WAF list item comment, typically with `^...$`. Example: - Instance A: `WAF_LIST_ITEM_COMMENT=managed-by-ddns-a`, `MANAGED_WAF_LIST_ITEMS_COMMENT_REGEX=^managed-by-ddns-a$` - Instance B: `WAF_LIST_ITEM_COMMENT=managed-by-ddns-b`, `MANAGED_WAF_LIST_ITEMS_COMMENT_REGEX=^managed-by-ddns-b$` ## 🚚 Non-Docker Setups These setups are for runtimes that are not additive changes on top of the Docker Compose template in [Step 1: Updating the Compose File](#docker-compose-template). ### ⚙️ Deploy as a system service ### 🦭 Run the container with Podman Start with the same image and environment variables shown in [Quick Start](#quick-start) or [Step 1: Updating the Compose File](#docker-compose-template), then adapt the run command to your Podman workflow. This README does not currently maintain Podman-specific commands, Quadlet files, or Compose conversions. ### ☸️ Run on Kubernetes ## 🛠️ Troubleshooting ### 🤔 I got exec /bin/ddns: operation not permitted Some Docker, kernel, and virtualization combinations do not work well with [`security_opt: [no-new-privileges:true]`](https://docs.docker.com/reference/cli/docker/container/run/). If this happens, try removing that one hardening option and start the container again. This slightly reduces security, so keep the other hardening options if possible. If removing `no-new-privileges` fixes the problem, keep it disabled for this container or adjust your security policy to allow this binary. If removing `no-new-privileges` does not help, try a minimal image such as `alpine` or another popular Docker image with the same hardening option. If that also fails, the problem is likely in the host environment rather than this updater. Reported cases have included older kernels and some QEMU/Proxmox-style virtualized setups. If none of these applies, please [open an issue on GitHub](https://github.com/favonia/cloudflare-ddns/issues/new/choose) and include your compose file with secrets redacted, `docker version`, `uname -a`, your host OS and virtualization platform (if any), and whether a minimal image such as `alpine` shows the same error. ### 🤔 I am getting error code: 1034 There have been reports of intermittent issues with the default provider `cloudflare.trace`. If you see `error code: 1034`, upgrade to version 1.15.1 or later, or switch to another provider such as `cloudflare.doh` or `url:`. ### 🤔 I got context deadline exceeded and IP detection failed The first thing to check is whether a container can reach Cloudflare from the Docker environment at all. A simple way to test that is to run a minimal image such as `alpine` and try both DNS resolution and HTTPS connectivity: docker run --rm alpine nslookup api.cloudflare.com docker run --rm alpine wget -qO- https://api.cloudflare.com/cdn-cgi/trace If `nslookup` fails, your Docker setup likely has a DNS problem. If `wget` fails, outbound HTTPS connectivity to Cloudflare is likely blocked or broken. If both commands work, try increasing `DETECTION_TIMEOUT` (for example, `DETECTION_TIMEOUT=1m`) in case requests are simply slow in your environment. If that still does not help, please [open a GitHub issue](https://github.com/favonia/cloudflare-ddns/issues/new/choose) and include your setup details, relevant configs with secrets redacted, and any logs you have so that we can investigate further. ### 🤔 Why did the updater detect a public IP address different from the WAN IP address on my router? If your router shows an address between `100.64.0.0` and `100.127.255.255`, you are likely behind [CGNAT (Carrier-grade NAT)](https://en.wikipedia.org/wiki/Carrier-grade_NAT). In that case, your ISP is not giving you a real public IP address, so ordinary DDNS cannot make your home network directly reachable from the Internet. Your options are usually to switch to an ISP that gives you a real public IP address or to use a different approach such as [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/). ### 🤔 How can I see the timestamps of the IP checks and/or updates? The updater does not add timestamps itself because most runtimes already do: - If you are using Docker Compose, Kubernetes, or Docker directly, add `--timestamps` when viewing the logs. - If you are using Portainer, [enable “Show timestamp” when viewing the logs](https://docs.portainer.io/user/docker/containers/logs). ## 🎛️ Further Customization ### ⚙️ All Settings The emoji “🧪” marks experimental features, and the emoji “🤖” marks technical details that most readers can skip on a first pass.

🔐 Cloudflare API Access ^{click to expand}

| Name | Meaning | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `CLOUDFLARE_API_TOKEN` | The [Cloudflare API token](https://dash.cloudflare.com/profile/api-tokens) to access the Cloudflare API | | `CLOUDFLARE_API_TOKEN_FILE` | An absolute path to a file that contains the [Cloudflare API token](https://dash.cloudflare.com/profile/api-tokens) to access the Cloudflare API | | `CF_API_TOKEN` (will be deprecated in version 2.0.0) | Same as `CLOUDFLARE_API_TOKEN` | | `CF_API_TOKEN_FILE` (will be deprecated in version 2.0.0) | Same as `CLOUDFLARE_API_TOKEN_FILE` |

🌐 DNS Record Scope ^{click to expand}

| Name | Meaning | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DOMAINS` | Comma-separated fully qualified domain names or wildcard domain names that the updater should manage for both `A` and `AAAA` records. Listing a domain in `DOMAINS` manages the same DNS records as listing the same domain in both `IP4_DOMAINS` and `IP6_DOMAINS`. | | `IP4_DOMAINS` | Comma-separated fully qualified domain names or wildcard domain names that the updater should manage for `A` records (in addition to those in `DOMAINS`) | | `IP6_DOMAINS` | Comma-separated fully qualified domain names or wildcard domain names that the updater should manage for `AAAA` records (in addition to those in `DOMAINS`) | | Name | Meaning | Default Value | | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | `MANAGED_RECORDS_COMMENT_REGEX` (available since version 1.16.0) | Regex that selects which DNS records this updater manages by their comments. Matched records are updated or deleted as needed; new records are created with comments that match. Uses [RE2](https://github.com/google/re2/wiki/Syntax) syntax (the Go `regexp` syntax, not Perl/PCRE). | `""` (empty regex; manages all DNS records) |

📋 WAF List Scope ^{click to expand}

| Name | Meaning | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 🧪 `WAF_LISTS` (available since version 1.14.0) |

🧪 Comma-separated references of [WAF lists](https://developers.cloudflare.com/waf/tools/lists/custom-lists/) the updater should manage. A list reference is written in the format `/` where `account-id` is your account ID and `list-name` is the list name; it should look like `0123456789abcdef0123456789abcdef/mylist`. If the referenced WAF list does not exist, the updater will try to create it.

🔑 The API token needs the **Account - Account Filter Lists - Edit** permission.
💡 See [how to find your account ID](https://developers.cloudflare.com/fundamentals/account/find-account-and-zone-ids/).

| | Name | Meaning | Default Value | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | | 🧪 `MANAGED_WAF_LIST_ITEMS_COMMENT_REGEX` (available since version 1.16.0) | 🧪 Regex that selects which WAF list items this updater manages by their comments. This lets multiple updater instances share one WAF list safely: matched items are updated or deleted as needed, and new items are created with comments that match. Uses [RE2](https://github.com/google/re2/wiki/Syntax) syntax (the Go `regexp` syntax, not Perl/PCRE). | `""` (empty regex; manages all WAF list items) |

🔍 IP Detection ^{click to expand}

| Name | Meaning | Default Value | | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | `IP4_PROVIDER` | This specifies how to detect the current IPv4 address. Available providers include `cloudflare.trace`, `cloudflare.doh`, `local`, `local.iface:`, `url:`, `url.via4:`, `url.via6:`, `static:,,...`, `static.empty`, `file:`, and `none`. The special `none` provider stops managing IPv4. See the provider table in this section for the detailed explanation. | `cloudflare.trace` | | `IP6_PROVIDER` | This specifies how to detect the current IPv6 address. Available providers include `cloudflare.trace`, `cloudflare.doh`, `local`, `local.iface:`, `url:`, `url.via4:`, `url.via6:`, `static:,,...`, `static.empty`, `file:`, and `none`. The special `none` provider stops managing IPv6. See the provider table in this section for the detailed explanation. | `cloudflare.trace` | | 🧪 `IP4_DETECTION_FILTER` (unreleased) | 🧪 Keep only detected IPv4 addresses that match the filter before updating `A` records or IPv4 WAF list items. If no detected IPv4 address matches, IPv4 is skipped for that round and existing managed IPv4 records and WAF list items are preserved. | `keep-all` | | 🧪 `IP6_DETECTION_FILTER` (unreleased) | 🧪 Keep only detected IPv6 addresses that match the filter before updating `AAAA` records or IPv6 WAF list items. If no detected IPv6 address matches, IPv6 is skipped for that round and existing managed IPv6 records and WAF list items are preserved. | `keep-all` | | `IP4_DEFAULT_PREFIX_LEN` (available since version 1.16.0) | The default CIDR prefix length for detected bare IPv4 addresses. When a provider discovers a bare address (without CIDR notation), this prefix length is attached. DNS records currently ignore this setting, but future features may use it. WAF lists use the prefix length to determine the stored range: for example, `24` stores each bare detection as a `/24` range. Valid range: 8–32. | `32` | | `IP6_DEFAULT_PREFIX_LEN` (available since version 1.16.0) | The default CIDR prefix length for detected bare IPv6 addresses. When a provider discovers a bare address (without CIDR notation), this prefix length is attached. For `AAAA` records, this length decides how many trailing bits `hostid6` replaces. WAF lists use the prefix length to determine the stored range: for example, `48` stores each bare detection as a `/48` range. Valid range: 12–128. 🤖 See [IPv6 Default Prefix Length Policy](docs/designs/features/ipv6-default-prefix-length-policy.markdown) for the design rationale behind the `/64` default (instead of `/128`). | `64` | | Provider Name | Explanation | | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cloudflare.trace` | Get the IP address by parsing the [Cloudflare debugging page](https://api.cloudflare.com/cdn-cgi/trace). **This is the default provider.** | | `cloudflare.doh` | Get the IP address by querying `whoami.cloudflare.` against [Cloudflare via DNS-over-HTTPS](https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/). | | `local` |

Get the IP address via local network interfaces and routing tables. The updater will use the local address that _would have_ been used for outbound UDP connections to Cloudflare servers. (No data will be transmitted.)

⚠️ The updater needs access to the host network (such as `network_mode: host` in Docker Compose) for this provider, for otherwise the updater will detect the addresses inside [the default bridge network in Docker](https://docs.docker.com/engine/network/drivers/bridge/) instead of those in the host network.

| | 🧪 `local.iface:` (available since version 1.15.0) |

🧪 Get IP addresses via the specific local network interface `iface`. Since version 1.16.0, the updater collects all matching global unicast addresses of the selected IP family (IPv4 or IPv6) instead of just the first one, then reconciles DNS records and WAF lists against that full set.

⚠️ The updater needs access to the host network (such as `network_mode: host` in Docker Compose) for this provider, for otherwise the updater cannot access host network interfaces.

🤖 The updater ignores the prefix length reported by the interface, because it commonly describes its local subnet, not the range the updater should claim. The updater uses the default prefix lengths from `IP4_DEFAULT_PREFIX_LEN` or `IP6_DEFAULT_PREFIX_LEN` instead.

| | `url:` |

Fetch the IP address from a URL. The provider format is `url:` followed by the URL itself. For example, `IP4_PROVIDER=url:https://api4.ipify.org` fetches the IPv4 address from . Currently, only HTTP(S) is supported.

The updater connects over IPv4 for `IP4_PROVIDER` and over IPv6 for `IP6_PROVIDER`. The intention is to query a public IP detection server with the correct IP family. If you want to override that, use `IP4_PROVIDER=url.via6:` or `IP6_PROVIDER=url.via4:` instead.

The response may also use CIDR notation. 🧪 It may contain multiple addresses using the line-based text format described after this table.

🕰️ Before version 1.15.0, `url:` did not enforce the matching IP family.

| | `url.via4:` (available since version 1.16.0) |

Fetch the IP address from a URL while always connecting to that URL over IPv4. It accepts the same CIDR notation and 🧪 multiple-address text format as `url:`.

The intention is to get an IPv6 address over IPv4 with `IP6_PROVIDER=url.via4:`. In comparison, `IP6_PROVIDER=url:` will get an IPv6 address over the matching IP family (IPv6).

| | `url.via6:` (available since version 1.16.0) |

Fetch the IP address from a URL while always connecting to that URL over IPv6. It accepts the same CIDR notation and 🧪 multiple-address text format as `url:`.

The intention is to get an IPv4 address over IPv6 with `IP4_PROVIDER=url.via6:`. In comparison, `IP4_PROVIDER=url:` will get an IPv4 address over the matching IP family (IPv4).

| | `file:` (available since version 1.16.0) |

Read the IP address from a local file. The path must be absolute.

The file is re-read on every detection cycle, so you can update it without restarting the updater.

🧪 The file may also use the line-based text format described after this table for multiple addresses.

⚠️ The file must be readable by the user configured by `user: "UID:GID"`.

| | `static:,,...` (available since version 1.16.0) |

Use one or more explicit IP addresses or addresses in CIDR notation as a fixed set, separated by commas. This is an advanced provider for tests, debugging, and special fixed-input setups.

⚠️ Most users should not use it for normal long-running DDNS.

🤖 The entries are parsed, deduplicated, sorted, and validated for the selected IP family via the same normalization pipeline used by other providers.

| | `static.empty` (available since version 1.16.0) |

Clear existing managed content for the selected IP family. In contrast, `none` preserves existing managed content for that family.

🧪 If you also use WAF lists, this clears managed items of that IP family but does not delete the list itself. The updater will try to delete the list on exit only when `DELETE_ON_STOP` is enabled.

⚠️ Most users should not use it for normal long-running DDNS.

| | `none` |

Stop managing the specified IP family for this run. For example `IP4_PROVIDER=none` stops managing IPv4. Existing managed DNS records of that IP family are preserved.

🧪 Existing managed WAF list items of that IP family are preserved too, because that family is out of scope. Use `static.empty` if you want to clear managed content for that family. As the support of WAF lists is still experimental, please [provide feedback](https://github.com/favonia/cloudflare-ddns/issues/new/choose) if this does not match your needs.

|

📅 Update Schedule and Lifecycle ^{click to expand}

| Name | Meaning | Default Value | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | `CACHE_EXPIRATION` | The expiration of cached Cloudflare API responses. It can be any positive time duration accepted by [time.ParseDuration](https://pkg.go.dev/time#ParseDuration), such as `1h` or `10m`. | `6h0m0s` (6 hours) | | `DELETE_ON_STOP` |

Whether managed DNS records and managed WAF content are deleted when the updater exits. It accepts any boolean value supported by [strconv.ParseBool](https://pkg.go.dev/strconv#ParseBool), such as `true`, `false`, `0`, or `1`.

DNS cleanup applies only to the IP families this updater is managing in that run.

🧪 For WAF lists, the updater deletes the whole list only when the updater manages both IP families and no filtering is enabled by `MANAGED_WAF_LIST_ITEMS_COMMENT_REGEX`. Otherwise shutdown cleanup keeps the list and deletes only managed items in the managed IP families.

| `false` | | `TZ` |

The timezone used for logging messages and parsing `UPDATE_CRON`. It can be any timezone accepted by [time.LoadLocation](https://pkg.go.dev/time#LoadLocation), including any IANA Time Zone.

🤖 The pre-built Docker images come with the embedded timezone database via the [time/tzdata](https://pkg.go.dev/time/tzdata) package.

| `UTC` | | `UPDATE_CRON` |

The schedule to re-check IP addresses and update DNS records and WAF lists (if needed). The format is [any cron expression accepted by the `cron` library](https://pkg.go.dev/github.com/robfig/cron/v3#hdr-CRON_Expression_Format) or the special value `@once`. The special value `@once` means the updater will terminate immediately after updating the DNS records or WAF lists, effectively disabling the scheduling feature.

🤖 The update schedule _does not_ take the time to update records into consideration. For example, if the schedule is `@every 5m`, and if the updating itself takes 2 minutes, then the actual interval between adjacent updates is 3 minutes, not 5 minutes.

| `@every 5m` (every 5 minutes) | | `UPDATE_ON_START` | Whether to check IP addresses (and possibly update DNS records and WAF lists) _immediately_ on start, regardless of the update schedule specified by `UPDATE_CRON`. It can be any boolean value accepted by [strconv.ParseBool](https://pkg.go.dev/strconv#ParseBool), such as `true`, `false`, `0`, or `1`. | `true` |

⏳ Operation Timeouts ^{click to expand}

| Name | Meaning | Default Value | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | `DETECTION_TIMEOUT` | The timeout of each attempt to detect IP address, per IP version (IPv4 and IPv6). It can be any positive time duration accepted by [time.ParseDuration](https://pkg.go.dev/time#ParseDuration), such as `1h` or `10m`. | `5s` (5 seconds) | | `UPDATE_TIMEOUT` | The timeout of each attempt to update DNS records, per domain and per record type, or per WAF list. It can be any positive time duration accepted by [time.ParseDuration](https://pkg.go.dev/time#ParseDuration), such as `1h` or `10m`. | `30s` (30 seconds) |

🛟 DNS and WAF Fallback Values ^{click to expand}

| Name | Meaning | Default Value | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | `PROXIED` |

Fallback proxy setting for DNS records managed by the updater. It can be any boolean value accepted by [strconv.ParseBool](https://pkg.go.dev/strconv#ParseBool), such as `true`, `false`, `0`, or `1`.

🤖 Advanced usage: it can also be a domain-dependent boolean expression, as described in the examples later in this section.

| `false` | | `TTL` | Fallback TTL (in seconds) for DNS records managed by the updater. | `1` (This means “automatic” to Cloudflare) | | `RECORD_COMMENT` | Fallback [record comment](https://developers.cloudflare.com/dns/manage-dns-records/reference/record-attributes/) for DNS records managed by the updater. | `""` | | 🧪 `WAF_LIST_DESCRIPTION` (available since version 1.14.0) |

🧪 Fallback description for WAF lists managed by the updater.

🤖 This matters only when the updater needs to create a new WAF list, because a WAF list has only one description.

| `""` | | 🧪 `WAF_LIST_ITEM_COMMENT` (available since version 1.16.0) | 🧪 Fallback comment for WAF list items managed by the updater. | `""` |

👁️ Logging ^{click to expand}

| Name | Meaning | Default Value | | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `EMOJI` | Whether the updater should use emojis in the logging. It can be any boolean value accepted by [strconv.ParseBool](https://pkg.go.dev/strconv#ParseBool), such as `true`, `false`, `0`, or `1`. | `true` | | `QUIET` | Whether the updater should reduce the logging. It can be any boolean value accepted by [strconv.ParseBool](https://pkg.go.dev/strconv#ParseBool), such as `true`, `false`, `0`, or `1`. | `false` |

📣 Notifications ^{click to expand}

| Name | Meaning | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `HEALTHCHECKS` |

The [Healthchecks ping URL](https://healthchecks.io/docs/) to ping when the updater successfully updates IP addresses, such as `https://hc-ping.com/` or `https://hc-ping.com//`

⚠️ The ping schedule should match the update schedule specified by `UPDATE_CRON`.
🤖 The updater can work with _any_ server following the [same Healthchecks protocol](https://healthchecks.io/docs/http_api/), including self-hosted instances of [Healthchecks](https://github.com/healthchecks/healthchecks). Both UUID and Slug URLs are supported, and the updater works regardless whether the POST-only mode is enabled.

| | `UPTIMEKUMA` |

The Uptime Kuma’s Push URL to ping when the updater successfully updates IP addresses, such as `https:///push/`. You can directly copy the “Push URL” from the Uptime Kuma configuration page.

⚠️ The “Heartbeat Interval” should match the update schedule specified by `UPDATE_CRON`.

| | `SHOUTRRR` |

Newline-separated [shoutrrr URLs](https://containrrr.dev/shoutrrr/latest/services/overview/) to which the updater sends notifications of IP address changes and other events. In other words, put one URL on each line. Blank lines and lines whose first non-whitespace character is `#` are ignored. Each shoutrrr URL represents a notification service; for example, `discord://@` means sending messages to Discord. If one URL needs spaces, percent-encode them to help the updater parse URLs.

If you configure this value via YAML, prefer literal block style \| over folded style >.

| | `SHOUTRRR_FILE` (unreleased) |

An absolute path to a file containing shoutrrr URLs, one per line. This is the file version of `SHOUTRRR`, useful for keeping URLs that embed secret tokens out of the environment (for example with [Docker secrets](https://docs.docker.com/compose/how-tos/use-secrets/)).

Blank lines and lines whose first non-whitespace character is `#` are ignored. If both `SHOUTRRR` and `SHOUTRRR_FILE` are set, they must specify the same URLs (order does not matter) or the updater refuses to start.

⚠️ The file must be readable by the user configured by `user: "UID:GID"`.

|

### 🔂 Restarting the Container If you are using Docker Compose, run `docker-compose up --detach` to reload settings. ## 🚵 Migration Guides

I am migrating from oznu/cloudflare-ddns (now archived) ^{click to expand}

⚠️ [oznu/cloudflare-ddns](https://github.com/oznu/docker-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 [network security design note](docs/designs/features/network-security-model.markdown) for more information. | Old Parameter | | Note | | -------------------------------------- | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `API_KEY=` | ⚠️ | Legacy global API keys are not supported. Please [generate a scoped API token](#cloudflare-api-token) and use `CLOUDFLARE_API_TOKEN=`. | | `API_KEY_FILE=/path/to/key-file` | ⚠️ | Legacy global API keys are not supported. Please [generate a scoped API token](#cloudflare-api-token), save it, and use `CLOUDFLARE_API_TOKEN_FILE=/path/to/token-file`. | | `ZONE=example.org` and `SUBDOMAIN=sub` | ✔️ | Use `DOMAINS=sub.example.org` directly | | `PROXIED=true` | ✔️ | Same (`PROXIED=true`) | | `RRTYPE=A` | ✔️ | Both IPv4 and IPv6 are enabled by default; use `IP6_PROVIDER=none` to stop managing IPv6 | | `RRTYPE=AAAA` | ✔️ | Both IPv4 and IPv6 are enabled by default; use `IP4_PROVIDER=none` to stop managing IPv4 | | `DELETE_ON_STOP=true` | ✔️ | Same (`DELETE_ON_STOP=true`) | | `INTERFACE=` | ✔️ | To automatically select the local address, use `IP4/6_PROVIDER=local`. 🧪 To select addresses of a specific network interface, use `IP4/6_PROVIDER=local.iface:` (available since version 1.15.0). Since version 1.16.0, the updater collects all matching global unicast addresses instead of just the first one, then reconciles DNS records and WAF lists against that full detected set. | | `CUSTOM_LOOKUP_CMD=cmd` | ❌ | Custom commands are not supported because there are no other programs in the minimal Docker image | | `DNS_SERVER=server` | ❌ | For DNS-based IP detection, the updater only supports secure DNS queries using Cloudflare’s DNS over HTTPS (DoH) server. To enable this, set `IP4/6_PROVIDER=cloudflare.doh`. To detect IP addresses via HTTPS by querying other servers, use `IP4/6_PROVIDER=url:` |

I am migrating from timothymiller/cloudflare-ddns ^{click to expand}

Since [timothymiller/cloudflare-ddns](https://github.com/timothymiller/cloudflare-ddns) 2.0.0, many setting names and features look very close to this updater. However, similar names do not necessarily mean identical semantics. Most mismatches will produce a clear startup error, but some differences are silent. If you only set a few options, checking the [documentation for those specific settings](#all-settings) should be quick and worthwhile. Here are two notable differences: - ⚠️ **`sub()` in `PROXIED` expressions:** In this updater, `sub(example.com)` matches _strict subdomains only_—it does **not** match `example.com` itself. In timothymiller/cloudflare-ddns, `sub(example.com)` matches `example.com` _and_ all its subdomains. Copying a `PROXIED` expression verbatim may silently change which domains are proxied. If you need to match a domain and all its subdomains, use `is(example.com) || sub(example.com)`. - `literal:` (timothymiller/cloudflare-ddns) is called `static:` in this updater (_e.g._, `IP4_PROVIDER=static:1.2.3.4`).

## 💖 Feedback Questions, suggestions, feature requests, and contributions are all welcome! Feel free to [open a GitHub issue](https://github.com/favonia/cloudflare-ddns/issues/new/choose). ## 📜 License The code is licensed under [Apache 2.0 with LLVM exceptions](./LICENSE). (The LLVM exceptions provide better compatibility with GPL 2.0 and other license exceptions.)

标签：Cloudflare, DDNS, Docker, EVTX分析, MITRE ATT&CK, PyVis, 安全防御评估, 日志审计, 版权保护, 网络调试, 自动化, 请求拦截, 运维工具