Skip to content

Cloudflare DDNS Updater

Keeps one public A record in sync with the server's current public IPv4 address. Runs every 5 minutes as a LaunchDaemon.

Current role: vpn.example.com (since 2026-11-04)

The record it updates is now vpn.example.com, not example.com.

  • At the Cloudflare Tunnel cutover (2026-11-03), example.com became a proxied CNAME to the tunnel, and this daemon was disabled.
  • That broke the home VPN. Tunnelblick connected to example.com:34443, which then resolved to Cloudflare, and Cloudflare does not proxy port 34443.
  • The fix: a separate DNS-only record, vpn.example.com, which this daemon keeps pointed at the home IP. See docs/components/home-vpn.md.

Rules that follow from this:

  • vpn.example.com must stay DNS only (grey cloud). A proxied record breaks the VPN the same way.
  • Do not retire this daemon while the VPN exists. The G2 plan's follow-up step that removes it is cancelled.
  • CLOUDFLARE_RECORD_ID is the ID of the vpn.example.com record. EXTERNAL_HOSTNAME stays example.com: it names the keychain account of the API token. DDNS_RECORD_NAME (vpn.example.com) is only used in log lines.

Why this exists

External access to the server is name-based (example.com) rather than IP-based. When the ISP rotates the WAN IP, the Cloudflare record must follow, otherwise remote access (Plex, Transmission, the dashboard) breaks.

An earlier DDNS implementation lived inside plex-vpn-bypass.sh, which was retired 2026-03 when the host-level PIA split-tunnel stack was replaced by a VPN-inside-the-container architecture. The A record then drifted silently. This updater is the standalone replacement.

Architecture

/Library/LaunchDaemons/com.<hostname>.cloudflare-ddns.plist
  (StartInterval = 300s, runs as root)
    → /usr/local/bin/cloudflare-ddns
        ├─ read CF_API_TOKEN from System keychain (same entry Caddy uses)
        ├─ GET https://api.ipify.org (fallback: ifconfig.me, icanhazip.com)
        ├─ GET /zones/<ZONE>/dns_records/<RECORD>  → current A-record content
        ├─ if equal: log heartbeat every 3600s, exit 0
        └─ if differs: PATCH /zones/<ZONE>/dns_records/<RECORD>, log result

The daemon runs as root so it can call security find-generic-password -s cloudflare-api-token -a <EXTERNAL_HOSTNAME> against the System keychain. The token never lands on disk.

Files (in mac-server-setup)

  • app-setup/cloudflare-ddns-setup.sh — deploy script; sources config.conf, validates inputs, substitutes placeholders, installs the daemon, bootstraps it, and tails the log for confirmation.
  • app-setup/templates/cloudflare-ddns.sh — updater script template.
  • app-setup/templates/com.cloudflare-ddns.plist — LaunchDaemon plist template.
  • tests/cloudflare-ddns.bats — unit tests (IP validator, JSON parser, branch coverage for the main loop with mocked network).

Deployed paths (on YOUR_SERVER)

  • /usr/local/bin/cloudflare-ddns (mode 0755, root-owned)
  • /Library/LaunchDaemons/com.<hostname>.cloudflare-ddns.plist (mode 0644)
  • /Users/operator/.local/state/cloudflare-ddns.log — log file
  • /Users/operator/.local/state/cloudflare-ddns.state — last_ip + last_heartbeat epoch

Configuration

Set these in app-setup/config/config.conf before running setup:

EXTERNAL_HOSTNAME="example.com"
CLOUDFLARE_ZONE_ID="<32-char hex zone ID>"
CLOUDFLARE_RECORD_ID="<32-char hex record ID>"

The token itself must already be in the System keychain (installed by caddy-setup.sh / Task 1 of the Cloudflare DNS-01 migration checklist). The DDNS setup script checks for the entry and fails loudly if absent.

Find the zone/record IDs from the Cloudflare dashboard or via:

CF_TOKEN=$(op read 'op://<vault>/<item>/API/zone DNS API token')
# Zone ID
curl -sH "Authorization: Bearer ${CF_TOKEN}" \
  'https://api.cloudflare.com/client/v4/zones?name=example.com' \
  | python3 -m json.tool | grep -E '"id"|"name"'
# Record ID (after filling in zone ID above)
curl -sH "Authorization: Bearer ${CF_TOKEN}" \
  "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/dns_records?type=A" \
  | python3 -m json.tool
unset CF_TOKEN

Deploy / redeploy

# On YOUR_SERVER, from the app-setup directory
cd ~/mac-server-setup/app-setup
sudo ./cloudflare-ddns-setup.sh

The script is idempotent: if the daemon is already loaded it is bootout'd before bootstrap. First cycle runs immediately on load (RunAtLoad=true).

Operations

# Status
sudo launchctl print system/com.<hostname>.cloudflare-ddns | head

# Force a run now (skip the 5-minute interval)
sudo launchctl kickstart -k system/com.<hostname>.cloudflare-ddns

# Tail the log
tail -f /Users/operator/.local/state/cloudflare-ddns.log

# Manual one-shot (bypasses the daemon, same effect)
sudo /usr/local/bin/cloudflare-ddns

# Stop
sudo launchctl bootout system/com.<hostname>.cloudflare-ddns

# Verify current A record from outside the LAN
dig +short vpn.example.com @1.1.1.1

Expected log lines

[2026-04-19 10:00:01] [cloudflare-ddns] INFO heartbeat ok — public=203.0.113.11 matches vpn.example.com
[2026-04-19 12:05:03] [cloudflare-ddns] INFO IP change detected: vpn.example.com 203.0.113.11 → 203.0.113.12
[2026-04-19 12:05:04] [cloudflare-ddns] INFO cloudflare A-record updated: vpn.example.com → 203.0.113.12
[2026-04-19 13:10:02] [cloudflare-ddns] WARN could not determine public IP from any provider — will retry next cycle

Heartbeats fire at most once per hour when nothing changes, so a silent log is itself a red flag.

Troubleshooting

cloudflare-api-token not found in System keychain

The Caddy setup stores this. Verify:

sudo security find-generic-password -s cloudflare-api-token -a example.com \
  /Library/Keychains/System.keychain

If missing, re-run the Caddy cloudflare checklist Task 1 or add manually:

sudo security add-generic-password -U \
  -s 'cloudflare-api-token' -a 'example.com' \
  -w '<token>' /Library/Keychains/System.keychain

cloudflare GET failed / cloudflare PATCH failed

The log includes the Cloudflare response JSON. Common causes:

  • Token revoked or expired → regenerate in Cloudflare dashboard and update the keychain entry.
  • Token missing Zone:DNS:Edit permission on the relevant zone.
  • Zone or record ID drifted (e.g., record deleted and recreated) → look up fresh IDs and redeploy.

could not determine public IP from any provider

All three external providers unreachable. Usually a transient upstream outage; the next cycle (5 min) will retry. If persistent:

  • curl -v https://api.ipify.org from YOUR_SERVER directly.
  • Check whether a local DNS or firewall rule is in the way (PIA split tunnel is gone, but VPN changes can recur).

Record still stale after deploy

RunAtLoad=true means the first cycle fires immediately on bootstrap. If the record still shows the old IP:

tail -20 /Users/operator/.local/state/cloudflare-ddns.log
sudo launchctl kickstart -k system/com.<hostname>.cloudflare-ddns

If the log shows INFO heartbeat ok — public=X matches ..., the record matches what the script saw. Your cache or the client resolver may still hold the old answer; dig directly at Cloudflare (@1.1.1.1) to confirm.

Tests

bats tests/cloudflare-ddns.bats

Covers: IPv4 validation, JSON parsing (top-level, dot-path, missing field, malformed), main loop with mocked keychain/public-IP/Cloudflare calls for both the no-change and change branches, plus failure modes (missing token, unreachable IP providers, Cloudflare 4xx).