cloudflare-ddns

🌟 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.

The emoji “🧪” marks experimental features, and the emoji “🤖” marks technical details that most readers can skip on a first pass.

✨ Highlights

✅ Comprehensive 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.

🌥️ Cloudflare-specific Features

• 📝 The updater preserves existing Cloudflare proxy statuses, TTLs, and comments for managed DNS records. You can set fallback values for cases where the updater needs to supply them.
• 📜 The updater can maintain lists of detected IP addresses. These lists can then be referenced in any Cloudflare product that uses Cloudflare’s Rules language, such as Cloudflare Web Application Firewall (WAF) and Cloudflare 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 or Uptime Kuma 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, 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.
• 🧰 The updater is designed to recover from transient network failures.

🔒 Security and Privacy

• 🙈 By default, public IP detection stays with Cloudflare: the cloudflare.trace provider contacts HTTPS trace endpoints operated by Cloudflare, and the updater already contacts Cloudflare to update DNS records. See IP Detection for the current endpoint list.

• 🛡️ By default, 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 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
  

  The GHCR mirror (available since version 1.17.1) can be verified with the same command by replacing the image reference favonia/cloudflare-ddns:1 with ghcr.io/favonia/cloudflare-ddns:1.

  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.

• 📦 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

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

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

🐋 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 because it includes several optional settings 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.

If you need a non-default Docker Compose deployment, see 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. Each setup shows a minimal delta. For the exact behavior of each environment variable, see 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:<ip1>,<ip2>,... 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 fetch fresh DNS records on each check, make the cache expire right away:

environment:
  - CACHE_EXPIRATION=1ns

After editing DNS records in Cloudflare, watch the updater logs to see how they are reconciled on the next scheduled check.

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 DNS records of that IP family are preserved. 🧪 If you also use WAF lists, existing items of that IP family are preserved there too.

Use IPv6 without sharing the host network

Use this when you want IPv6 support but do not want network_mode: host.

services:
  cloudflare-ddns:
    # Remove this line:
    # network_mode: host

After removing network_mode: host, follow the official Docker instructions for enabling IPv6 on your Docker bridge network.

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.trace, cloudflare.doh) or other IP detection websites (url:<url>) to see the public IPs via a specific interface.

One possible approach is to use IPvlan network driver 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 <iface> is the name of the host interface:

networks:
  ddns:
    driver: ipvlan
    driver_opts:
      parent: <iface>
      ipvlan_mode: l2
    ipam:
      config:
        - subnet: <subnet>
          gateway: <gateway>

Replace <iface>, <subnet>, and <gateway> to match the host interface you want the container to use.

• On the host, run ip route show dev <iface> proto kernel and use the subnet in CIDR notation as your <subnet>, such as 192.168.1.0/24.
• On the host, run ip route show default dev <iface> and use the via address as your <gateway>, 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.

🧪 local.iface:<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. 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$

This setup requires MANAGED_RECORDS_COMMENT_REGEX (available since version 1.16.0).

Share WAF lists across updater instances

Use this when multiple instances share WAF lists. 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$

🧪 This setup requires WAF_LIST_ITEM_COMMENT (available since version 1.16.0) and MANAGED_WAF_LIST_ITEMS_COMMENT_REGEX (available since version 1.16.0). Both settings are experimental.

🚚 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.

⚙️ Deploy as a system service

The repository currently includes community-contributed sample configurations for OpenBSD.

🦭 Run the container with Podman

Start with the same image and environment variables shown in Quick Start or Step 1: Updating the Compose File, 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

Due to high maintenance costs, the dedicated Kubernetes instructions have been removed. You can still generate Kubernetes configurations from the Docker Compose template using Kompose version 1.35.0 or later. A simple Deployment is sufficient here; there is no inbound traffic, so a Service is not required. This README does not maintain first-party Kubernetes manifests.

🚦 Exit Status

• Scheduled runs (the default): The updater repeats updates on its schedule and continues after failed updates. When stopped normally, it returns 0, or 1 if cleanup requested by DELETE_ON_STOP=true fails.
• One-shot runs (UPDATE_CRON=@once): The updater exits after one update or cleanup. It returns 0 on success, including when no changes are needed, or 1 if the update or cleanup fails or is interrupted before completion.

Startup and configuration errors return 1.

🤖 Scheduled shutdown cleanup can return 0 once Cloudflare accepts the deletion request, without waiting for deletion to finish. One-shot cleanup waits for completion within the configured timeout.

🤖 Heartbeat and notification delivery failures do not change the exit status.

🛠️ 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]. 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 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:<url>.

🤔 I got context deadline exceeded and IP detection failed

First check the updater logs to identify the provider and IP family that timed out. If the failed provider is cloudflare.trace, test every current built-in endpoint from a diagnostic container that shares the updater container’s existing network stack. The commands below use the cloudflare-ddns service name from this README and test IPv4; replace the service name if yours differs, and replace --ipv4 with --ipv6 for an IPv6 failure. If the updater receives explicit proxy environment variables, pass the same variables to the diagnostic container.

DDNS_CONTAINER="$(docker-compose ps -q cloudflare-ddns)"

docker run --rm --network "container:${DDNS_CONTAINER}" curlimages/curl:latest --fail --show-error --silent --ipv4 https://api.cloudflare.com/cdn-cgi/trace
docker run --rm --network "container:${DDNS_CONTAINER}" curlimages/curl:latest --fail --show-error --silent --ipv4 https://www.cloudflare.com/cdn-cgi/trace
docker run --rm --network "container:${DDNS_CONTAINER}" curlimages/curl:latest --fail --show-error --silent --ipv4 https://connectivity.cloudflareclient.com/cdn-cgi/trace

If curl reports Could not resolve host, DNS resolution failed in the updater’s container network. Check the host’s DNS configuration and Docker’s DNS services. A failure at one endpoint does not by itself prevent detection, because another endpoint may return a valid response. If any of the three commands succeeds but detection still times out, check the updater logs for response-validation failures, then try increasing DETECTION_TIMEOUT (for example, DETECTION_TIMEOUT=1m).

If that still does not help, please open a GitHub issue 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). 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.

🤔 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.

🎛️ Further Customization

⚙️ All Settings

🔂 Restarting the Container

If you are using Docker Compose, run docker-compose up --detach to reload settings.

🚵 Migration Guides

💖 Feedback

Questions, suggestions, feature requests, and contributions are all welcome! Feel free to open a GitHub issue.

📜 License

The code is licensed under Apache 2.0 with LLVM exceptions. (The LLVM exceptions provide better compatibility with GPL 2.0 and other license exceptions.)