Modern Dynamic DNS: Cloudflare API Automation & Split-Horizon Resolution

Before modern cloud APIs, dynamic DNS (DDNS) meant running obscure background daemons (like ddclient or inadyn) that scraped third-party IP reflection sites and pushed updates over unauthenticated protocols to free DNS providers.

Today, DNS is managed via programmatic API tokens against enterprise-grade anycast infrastructure. This guide covers automated Cloudflare DDNS integration and the architectural advantages of Split-Horizon (Split-Brain) DNS behind hardware edge gateways.

⚡ Quick Runbook: 60-Second Implementation

TL;DR: Copy and deploy the baseline production definition directly onto your host:

services:
  cloudflare-ddns:
    image: favonia/cloudflare-ddns:latest
    container_name: cloudflare-ddns
    restart: unless-stopped
    environment:
      - CLOUDFLARE_API_TOKEN_FILE=/run/secrets/cf_api_token
      - DOMAINS=vpn.example.com,home.example.com
      - PROXIED=false  # Set false for WireGuard/VPN endpoints; true for web
      - UPDATE_CRON=@every 15m
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    secrets:
      - cf_api_token

secrets:
  cf_api_token:
    file: ./secrets/cf_api_token

1. The Cloudflare API v4 Advantage

Managing dynamic records through Cloudflare provides:

Scoped API Tokens: Tokens restricted strictly to Zone:DNS:Edit on a single domain, eliminating security risks associated with global account API keys.
Edge Proxy Protection: Cloudflare edge nodes proxy traffic, hiding your residential or datacenter WAN IP from public lookup.
Immediate TTL Propagation: Automatic DNS propagation across global edge nodes in under 5 seconds.

2. Containerized Cloudflare DDNS Deployment

Instead of installing legacy Perl scripts on your host, run a lightweight, unprivileged Docker container:

services:
  cloudflare-ddns:
    image: favonia/cloudflare-ddns:latest
    container_name: cloudflare-ddns
    restart: unless-stopped
    environment:
      - CLOUDFLARE_API_TOKEN_FILE=/run/secrets/cf_api_token
      - DOMAINS=vpn.example.com,home.example.com
      - PROXIED=false  # Set false for WireGuard/VPN endpoints; true for web
      - UPDATE_CRON=@every 15m
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    secrets:
      - cf_api_token

secrets:
  cf_api_token:
    file: ./secrets/cf_api_token

3. Split-Horizon DNS: Avoiding NAT Loopback Hairpinning

When you are inside your home or office LAN, accessing your local servers (e.g. nas.example.com) by routing out to your public IP and hair-pinning back through NAT adds unnecessary firewall overhead and reduces bandwidth to WAN speeds.

The Modern Solution: Split-Horizon DNS

Public View: External DNS queries to nas.example.com resolve to your public IP or Cloudflare Tunnel edge.
Internal View: Your local router/gateway (such as Firewalla, Pi-hole, or AdGuard Home) intercepts the domain and immediately returns the local LAN address (e.g. 192.168.1.50).

On a modern gateway like Firewalla:

Navigate to DNS Service > Custom DNS Rules.
Tap Add Custom DNS Rule.
Map nas.example.com directly to your local reverse proxy or server IP (192.168.1.50).

Now internal file transfers, video streams, and backups achieve full 10GbE / 2.5GbE local line rate with zero external bandwidth consumption.

Modern Dynamic DNS: Cloudflare API Automation & Split-Horizon Resolution

⚡ Quick Runbook: 60-Second Implementation

1. The Cloudflare API v4 Advantage

2. Containerized Cloudflare DDNS Deployment

3. Split-Horizon DNS: Avoiding NAT Loopback Hairpinning

Related Runbooks in This Series