Dynamic DNS Automation Auditable Open Source • Cloudflare API

Cirrusync: Cloudflare Dynamic DNS Client

A lightweight, auditable Dynamic DNS client for Cloudflare. Automatically discovers public IPv4 and IPv6 addresses, compares them against target DNS zone records, and modifies only out-of-date entries under systemd or automated cron schedules.

View on GitHub → Configuration Guide ← All Tools & Ecosystem
Provider: Cloudflare v4 API
Record Types: A (IPv4) • AAAA (IPv6)
Target Platform: Linux / systemd (Debian 12, Ubuntu 22.04+) • Rust Daemon
Auditable Simplicity

Designed for Transparency & Least Privilege

Unlike opaque monolithic DDNS daemons, Cirrusync is built with clean, auditable logic focusing exclusively on Cloudflare DNS state synchronization:

SYNCHRONIZATION CYCLE

Dynamic DNS State Reconciliation Cycle

Rust • Cloudflare API v4 • Least-Privilege Scoped Tokens
Cirrusync Dynamic DNS State Reconciliation Cycle Diagram showing the four-stage reconciliation cycle of Cirrusync: discovering public IP addresses, querying Cloudflare DNS records via API v4, evaluating IP deltas, and executing conditional record updates. 1. DUAL-STACK PROBES IP Discovery External WAN endpoints Redundant Probes Cloudflare trace, ipify, icanhazip Public IPv4 WAN Detects NAT gateway address Global IPv6 GUA Global unicast interface IP 2. ZONE QUERY Cloudflare API v4 GET Current State Scoped Bearer Auth Restricted Zone.DNS:Edit token GET A & AAAA Records Fetches published DNS entries TTL & Proxy Attributes Preserves Cloudflare proxy state 3. RECONCILIATION Delta Comparison Drift Detection Diff Active vs WAN Identifies IP discrepancies Zero-Op Bypass No API mutations if matching Mutation Dispatch Triggers PUT only on change 4. RECORD SYNC API Mutation PUT Record & Sleep PUT Update Updates A / AAAA Audit Log Structured events systemd Timer Idles until next tick
State Reconciliation Cycle: Cirrusync runs an auditable, four-stage reconciliation loop. It discovers external dual-stack addresses, inspects live Cloudflare DNS records using least-privilege tokens, and executes API mutations only when IP drift is detected, eliminating unnecessary write requests and rate limiting.

Dual-Stack Discovery

Determines the host's true public IPv4 and IPv6 addresses via redundant external endpoints, preventing incorrect LAN address updates.

Scoped API Token Security

Operates under Cloudflare's least-privilege token model (`Zone.DNS:Edit`). Never requires Global API Keys or master account credentials.

Differential Updates Only

Queries existing Cloudflare records first and executes HTTP mutations only when IP drift is detected, avoiding API rate limits and log spam.

Multi-Zone & Multi-Record

Synchronizes multiple domain names across different Cloudflare DNS zones in a single execution loop with isolated per-zone error reporting.

systemd Native Service

Includes production systemd service definitions with security hardening (sandboxing, private temporary directories, and non-root execution).

One-Shot Test Mode

Supports manual single-run sync via command line for verification, CI pipelines, or lightweight cron-based task runners.

Operational Boundary Notice
Technical Scope Limitation: Dynamic DNS updates public DNS records to match an external IP address; it does NOT circumvent Carrier-Grade NAT (CGNAT), solve missing router port-forwarding rules, bypass ISP port blocks, or adjust local router firewall filters. For hosts behind CGNAT, combine with a VPN tunnel, overlay network, or relay.
Setup & Config

Configuration Workflow

Setup is managed through a simple TOML configuration file:

/etc/cirrusync/cirrusync.toml

# Cloudflare Scoped API Token (Zone.DNS:Edit)

api_token = "YOUR_CLOUDFLARE_SCOPED_TOKEN"


# Target DNS records to synchronize

[[records]]

zone_id = "0123456789abcdef0123456789abcdef"

name = "vpn.example.com"

types = ["A", "AAAA"]

proxied = false


# Run a single synchronization test

cirrusync --once --config /etc/cirrusync/cirrusync.toml

View Cirrusync on GitHub →