cloudflare-ddns: Keep Cloudflare DNS Records in Sync

Overview

cloudflare-ddns is a Go-based updater for Cloudflare DNS. It detects a machine’s public IP addresses and reconciles them with DNS records through the Cloudflare API, helping self-hosters keep domains pointed at changing home or server connections. It runs as a small Docker image or directly from Go source.

Beyond basic dynamic DNS, it can maintain Cloudflare WAF lists and send status or change notifications. Its design emphasizes secure IP detection over HTTPS or DNS over HTTPS, preservation of existing DNS record attributes, and recovery from transient network failures.

Key Features

• Manages A and AAAA records for domains across Cloudflare zones, including wildcard and internationalized domain names.
• Detects public IPv4 and IPv6 addresses through Cloudflare trace or DNS-over-HTTPS, with configurable alternative providers.
• Preserves existing DNS proxy settings, TTLs, and comments where possible, with configurable fallback values.
• Optionally maintains Cloudflare WAF lists with detected addresses.
• Supports scheduled updates, one-time runs, and cleanup of managed records when stopping.
• Integrates with Healthchecks, Uptime Kuma, and notification services supported by shoutrrr.
• Provides Docker deployment options with security-hardening guidance and supports running directly from Go source.

Use Cases

• A self-hoster can keep a home server’s Cloudflare DNS records current as the ISP changes its public IP.
• A user with IPv4-only or IPv6-only connectivity can manage just the address family their network supports.
• A Cloudflare administrator can publish changing IP ranges to WAF lists for use in Cloudflare rules.
• An operator can monitor a scheduled updater with Healthchecks, Uptime Kuma, or a shoutrrr-supported notification service.

Getting Started

Create a Cloudflare API token with the required DNS edit permission, then run the Docker image with your token and domains:

docker run --network host \
  -e CLOUDFLARE_API_TOKEN=YOUR-CLOUDFLARE-API-TOKEN \
  -e DOMAINS=example.org,www.example.org \
  favonia/cloudflare-ddns:1

See the README for Docker Compose setup, token permissions, settings, and alternative deployment options.

Considerations

• The project is active: it has recent commits, regular releases, and recent merged pull requests. Its contributor base includes eight people, and the measured contributor concentration is not flagged as a project risk.
• The updater needs outbound network access to detect addresses and reach the Cloudflare API. The default providers use Cloudflare endpoints; some local-interface detection modes require access to the host network.
• Docker Compose and Kubernetes-specific instructions are not maintained as first-party deployment guidance. The README suggests generating Kubernetes configuration from the Compose template, but does not provide maintained manifests.
• The project is licensed under Apache-2.0. Review the license terms for your distribution and use.