DevOps & Infrastructure • • 3 min read

Automate Dynamic DNS with Cloudflare API: A Robust Guide

Managing a home server or a local lab often comes with a common hurdle: the Dynamic IP address. While services like No-IP or DynDNS offer solutions, their free tiers usually require manual confirmation every 30 days. This manual intervention is prone to human error and service downtime.

A more professional and permanent solution is to use Cloudflare as your DNS provider and leverage its powerful API to create your own Dynamic DNS (DDNS) client. This guide provides a step-by-step technical workflow to automate IP updates.

Prerequisites

  • A domain pointed to Cloudflare nameservers.
  • A Linux-based server (Ubuntu, Raspberry Pi, etc.) or a environment capable of running Bash scripts.
  • Basic knowledge of the command line and curl.

Step 1: Generate a Cloudflare API Token

For security reasons, do not use your Global API Key. Instead, create a scoped token:

  1. Log in to the Cloudflare Dashboard and go to My Profile > API Tokens.
  2. Click Create Token and use the Edit zone DNS template.
  3. Under Permissions, ensure it says: Zone - DNS - Edit.
  4. Under Zone Resources, select your specific domain.
  5. Copy the generated token safely.

Step 2: Retrieve Zone and Record IDs

You need two IDs to target the correct DNS record via API: the Zone ID (found on your domain's Overview page) and the Record ID. You can find the Record ID using the following command:

curl -X GET "https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/dns_records?name=yourdomain.com" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json"

Step 3: The Automation Script

Create a script named update-ddns.sh. This script fetches your current public IP and updates Cloudflare only if the IP has changed to minimize API calls.

#!/bin/bash

# Configuration
API_TOKEN="your_api_token"
ZONE_ID="your_zone_id"
RECORD_ID="your_record_id"
RECORD_NAME="home.yourdomain.com"

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

# Update DNS Record
curl -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\":120,\"proxied\":false}"

echo "DNS Updated to $CURRENT_IP"

Step 4: Scheduling with Cron

To make this truly "set and forget," schedule the script to run every 5 or 10 minutes using Cron.

# Open crontab
crontab -e

# Add this line to run every 5 minutes
*/5 * * * * /bin/bash /path/to/update-ddns.sh

Strategic Insights

Security First

Always use Scoped API Tokens instead of Global Keys. If your server is compromised, a scoped token limits the attacker's ability to only modify DNS for a single domain rather than taking over your entire account.

TTL and Caching

Set a low TTL (Time To Live), such as 120 seconds (2 minutes). This ensures that when your IP changes, the DNS propagation happens quickly, reducing downtime for your services.

← Back to Blog