DPTCloud
Back to articles
Technology Insight

Building Your Own Dynamic DNS (DDNS) System with Cloudflare API and Cronjob: A Enterprise Guide

June 3, 2026

Introduction to the Dynamic IP Dilemma in Modern Infrastructure

In contemporary enterprise environments and advanced homelab setups, maintaining continuous remote access to local infrastructure is a fundamental requirement. Whether managing a self-hosted private cloud, a staging server, or an edge-computing gateway, administrators rely on Domain Name System (SNAM) records to point external traffic to internal network assets. However, residential and standard commercial internet service providers (ISPs) frequently cycle public IP addresses—a practice known as dynamic IP assignment.

When an ISP alters your public WAN IP, established DNS records break, cutting off remote management pipelines, VPN connections, and hosted services. Historically, organizations turned to commercial Dynamic DNS (DDNS) providers. While functional, these proprietary services often impose rigid subdomains, hidden subscription fees, or annoying manual monthly renewals. For a modern engineering team, a more robust, cost-effective, and fully customizable solution is available: leveraging the enterprise-grade infrastructure of Cloudflare via its robust developer API, combined with the proven automation of a Linux cronjob.

---

Why Cloudflare and Cronjobs? The Architecture of Choice

Building a custom DDNS solution requires a highly reliable DNS provider with an accessible API and a lightweight orchestration agent that runs locally within the dynamic network. Cloudflare stands out as the optimal choice for several distinct reasons:

  • Enterprise Reliability: Cloudflare operates one of the world's fastest and most reliable global Anycast networks, ensuring DNS updates propagate within seconds.
  • Granular API Permissions: Modern Cloudflare API tokens can be restricted to specific zones and permissions, adhering perfectly to the principle of least privilege.
  • Zero Financial Overhead: The core DNS management features, including API access and standard proxying capabilities, are entirely free of charge for custom domains.
  • Minimal Footprint: By utilizing standard POSIX shell scripting and a cron daemon natively available on Linux systems, you eliminate the need to run heavy third-party containerized daemons or background software layers.

The system architecture functions as a state machine. A localized shell script runs periodically via the cron daemon. It polls an external authority to determine the network's current public IP address, compares it against the existing DNS record stored in Cloudflare, and dispatches an authenticated HTTP PATCH or PUT request to update the record only when a change is detected. This minimizes unnecessary API overhead and avoids potential rate-limiting.

---

Prerequisites and Security Configurations

Before deploying the automation script, certain administrative configurations must be completed within your Cloudflare dashboard to ensure security and accessibility.

Step 1: Point Your Name Servers to Cloudflare

Ensure that your custom domain name is active within Cloudflare. You will need to replace your registrar's default nameservers with the specific Anycast nameservers provided by Cloudflare during the domain onboarding process. Allow sufficient time for global DNS propagation before proceeding.

Step 2: Generate a Secure API Token

Do not use your Global API Key for this automation task. If a script on a local server is compromised, a Global Key gives attackers full control over your entire Cloudflare account. Instead, generate a restricted API Token:

  1. Navigate to your Cloudflare Profile, select the API Tokens tab, and click Create Token.
  2. Choose the Edit zone DNS template.
  3. Under Permissions, ensure it reads: Zone - DNS - Edit.
  4. Under Zone Resources, restrict the scope to Specific zone and select your target domain.
  5. Click Continue to summary and generate the token. Copy it immediately, as it will not be displayed again.
Security Best Practice: Keep this token strictly confidential. Store it securely and never commit it in plaintext to public version control systems like GitHub.
---

The Automation Engine: Creating the Shell Script

With your API token ready, log into your local Linux server to construct the automation script. This script utilizes common utilities: curl for HTTP requests and jq for parsing JSON data structures. Ensure these are installed via your package manager (e.g., sudo apt install curl jq on Debian/Ubuntu systems).

Create a new file named cloudflare-ddns.sh in a secure directory, such as /usr/local/bin/, and insert the following codebase:

#!/bin/bash

# Configuration Variables
API_TOKEN="your_cloudflare_api_token_here"
ZONE_NAME="yourdomain.com"
RECORD_NAME="vpn.yourdomain.com"
TTL=120
PROXY=false

# Fetch current public WAN IP
CURRENT_IP=$(curl -s https://api.ipify.org)

if [ -z "$CURRENT_IP" ]; then
    echo "Error: Unable to retrieve current public IP address."
    exit 1
fi

# Retrieve Zone ID from Cloudflare API
ZONE_ID=$(curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=$ZONE_NAME" \
     -H "Authorization: Bearer $API_TOKEN" \
     -H "Content-Type: application/json" | jq -r '.result[0].id')

if [ -z "$ZONE_ID" ] || [ "$ZONE_ID" == "null" ]; then
    echo "Error: Failed to fetch Zone ID for $ZONE_NAME."
    exit 1
fi

# Retrieve Record ID and Existing IP from Cloudflare API
RECORD_DATA=$(curl -s -X GET "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records?name=$RECORD_NAME&type=A" \
     -H "Authorization: Bearer $API_TOKEN" \
     -H "Content-Type: application/json")

RECORD_ID=$(echo "$RECORD_DATA" | jq -r '.result[0].id')
CLOUDFLARE_IP=$(echo "$RECORD_DATA" | jq -r '.result[0].content')

# Validate and Update if necessary
if [ "$CURRENT_IP" == "$CLOUDFLARE_IP" ]; then
    echo "Success: IP addresses match ($CURRENT_IP). No update required."
    exit 0
else
    echo "Notice: IP mismatch detected. Local: $CURRENT_IP vs Cloudflare: $CLOUDFLARE_IP. Initiating update..."
    
    UPDATE_RESPONSE=$(curl -s -X PUT "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records/$RECORD_ID" \
         -H "Authorization: Bearer $API_TOKEN" \
         -H "Content-Type: application/json" \
         --data "{\"type\":\"A\",\"name\":\"$RECORD_NAME\",\"content\":\"$CURRENT_IP\",\"ttl\":$TTL,\"proxied\":$PROXY}")
         
    SUCCESS=$(echo "$UPDATE_RESPONSE" | jq -r '.success')
    
    if [ "$SUCCESS" == "true" ]; then
        echo "Success: DNS record updated to point to $CURRENT_IP."
    else
        echo "Error: Failed to update DNS record. Cloudflare API Response: $UPDATE_RESPONSE"
        exit 1
    fi
fi

After saving the script, apply the proper filesystem security permissions. Execute the following command to make the script executable by the owner, preventing unauthorized system users from reading your embedded API keys:

sudo chmod 700 /usr/local/bin/cloudflare-ddns.sh
---

Automating Execution via System Cron

Now that the dynamic script behaves predictably when run manually, you must integrate it with the system's cron daemon to guarantee execution at fixed intervals. For general use cases, running the synchronization check every 5 to 15 minutes provides excellent availability without abusing external APIs.

Open the crontab configuration editor for the administrative root user:

sudo crontab -e

Append the following directive to the very bottom of the file to execute the script every 5 minutes and route all outputs to a system log file for historical debugging:

*/5 * * * * /usr/local/bin/cloudflare-ddns.sh >> /var/log/cloudflare-ddns.log 2>&1

Save and close the editor. The cron daemon will automatically parse and load the updated schedule configuration. To prevent your log file from consuming unbounded disk space over months of operational runtime, consider configuring a brief logrotate rule targeting /var/log/cloudflare-ddns.log.

---

Advanced Strategy: To Proxy or Not To Proxy?

One distinct advantage of building a dynamic DNS system over Cloudflare instead of legacy providers is the ability to toggle Cloudflare's global reverse proxy network via the "proxied": true/false flag in the API payload. Understanding this mechanism is vital:

  • Proxied (True): Cloudflare hides your origin server's public dynamic IP behind their Anycast proxies. Web traffic (HTTP/HTTPS) benefits from advanced DDoS mitigation, WAF rules, and free SSL/TLS acceleration. However, this is strictly limited to HTTP/HTTPS traffic unless using specialized Cloudflare Spectrum services.
  • Unproxied (False): Also known as a standard Grey Cloud record. This configuration acts as a pure DNS mapping solution, resolving the domain directly to your public IP. Choose this if you intend to establish custom non-HTTP connections, such as standard SSH ports, WireGuard VPN tunnels, or custom game server payloads.
---

Conclusion and Verification

You have successfully engineered an independent, enterprise-grade Dynamic DNS infrastructure. To verify its end-to-end functionality, log into your residential or network router and trigger a forced IP renewal, or simply wait for your ISP to assign a new address naturally. Check your localized logs via tail -f /var/log/cloudflare-ddns.log to confirm that the script captures the delta change and updates the record within your Cloudflare panel.

By managing this logic yourself, you gain absolute sovereignty over your network's DNS layer, increase local system visibility, and reduce dependencies on proprietary external software clients. This straightforward integration demonstrates the profound capability of leveraging modern web APIs with foundational Unix system automation tools.

Building Your Own Dynamic DNS (DDNS) System with Cloudflare API and Cronjob: A Enterprise Guide | DPTCloud