DDNS Client Cloudflare

Homepage | API Documentation

Compatibility:

• OpenWrt: 22.03 and newer, SNAPSHOT
• ddns-scripts: 2.8.2-93 or newer
• Package: ddns-scripts-cloudflare

New Feature (2026): API-based registered IP verification is now supported. This solves the orange cloud proxy IP detection problem and is available in ddns-scripts 2.8.2-93 and later.

Cloudflare is a popular DNS provider that also offers CDN and DDoS protection services. OpenWrt's ddns-scripts fully support Cloudflare dynamic DNS updates to both IPv4 (A) and IPv6 (AAAA) records using modern API authentication. Note that the “-v4” in the cloudflare.com-v4 ddns script refers to the API version, not the IP version.

The DDNS API can only update an existing record - ensure the target DNS record (A or AAAA as required) exists in Cloudflare, creating it manually if required (an A record for subdomain.example.com in the example below).

Most users should use this configuration:

service_name    cloudflare.com-v4
domain          subdomain@example.com
username        Bearer
password        your_api_token_here
interface       wan
use_https       1
cacert          /etc/ssl/certs

Using Cloudflare's proxy (orange cloud 🟠)? Add option use_api_check '1' to prevent false update detections. See API-based IP verification below.

What you need:

1. A Cloudflare account with your domain configured
2. An API Token with DNS edit permissions (see setup below)
3. Package ddns-scripts-cloudflare installed

Cloudflare supports two authentication methods. Use API Tokens unless you have a specific reason to use the legacy method.

API Tokens provide secure, scoped access to your Cloudflare account. This is the recommended authentication method.

1. Log in to Cloudflare at dash.cloudflare.com
2. Navigate to My Profile (top right) → API Tokens
3. Click Create Token
4. Click Use template next to “Edit zone DNS”
5. Under Zone Resources:
   • Select Include → Specific zone → your domain
6. Under Permissions: Verify it shows Zone / DNS / Edit
7. Click Continue to summary
8. Click Create Token
9. Copy the token - you won't be able to see it again!

Via LuCI (Web Interface):

Navigate to Services → Dynamic DNS → Edit your service

• DDNS Service provider: cloudflare.com-v4
• Lookup Hostname: subdomain.example.com (your full domain name)
• Domain: subdomain@example.com (use @ symbol to separate subdomain from domain)
• Username: Bearer (exactly as shown, case-sensitive)
• Password: Paste your API token
• Interface: Select your WAN interface (usually wan for IPv4/A record, or wan6 for IPv6/AAAA)
• Use HTTP Secure: ✓ Enabled
• Path to CA-Certificate: /etc/ssl/certs

Via Command Line:

uci set ddns.cloudflare=service
uci set ddns.cloudflare.service_name='cloudflare.com-v4'
uci set ddns.cloudflare.domain='subdomain@example.com'
uci set ddns.cloudflare.username='Bearer'
uci set ddns.cloudflare.password='your_api_token_here'
uci set ddns.cloudflare.interface='wan'
uci set ddns.cloudflare.use_https='1'
uci set ddns.cloudflare.cacert='/etc/ssl/certs'
uci set ddns.cloudflare.enabled='1'
uci commit ddns
/etc/init.d/ddns restart

Warning: The Global API Key grants full access to your Cloudflare account. Use API Tokens instead whenever possible.

1. Log in to Cloudflare
2. Navigate to My Profile → API Tokens
3. Scroll down to API Keys section
4. Click View next to “Global API Key”
5. Enter your password to reveal the key

service_name    cloudflare.com-v4
domain          subdomain@example.com
username        your.email@example.com
password        your_global_api_key
interface       wan
use_https       1
cacert          /etc/ssl/certs

Cloudflare uses a special format to specify which DNS record to update:

Format: subdomain@zone

• Everything before @ becomes the hostname
• Everything after @ is your zone (domain registered with Cloudflare)
• For apex domain, use just example.com or @example.com

What is this?

When Cloudflare's proxy is enabled (orange cloud icon 🟠), DNS lookups return Cloudflare's edge IP addresses instead of your actual registered IP. This causes the DDNS script to incorrectly detect that an update is needed on every check, wasting API calls and logging unnecessary updates.

The new use_api_check feature solves this by querying Cloudflare's API directly to retrieve your actual registered IP, bypassing DNS entirely.

When do you need this?

Enable API-based IP verification if:

• You use Cloudflare's proxy (orange cloud 🟠) on your DDNS record
• Your logs show constant “Update needed” messages even when your IP hasn't changed
• You want to reduce unnecessary API calls to Cloudflare

Note: This is entirely optional. If you're not using Cloudflare's proxy (gray cloud ☁️), you don't need this feature.

How it works:

1. When use_api_check='0' or unset: Uses DNS lookup (default behavior)
2. When use_api_check='1': Queries Cloudflare API for the registered IP
3. If API query fails: Automatically falls back to DNS lookup (safe)

How to enable it:

Add this option to your configuration:

option use_api_check '1'

Full example with API verification enabled:

# /etc/config/ddns
config service 'cloudflare'
        option service_name 'cloudflare.com-v4'
        option enabled '1'
        option domain 'home@example.com'
        option username 'Bearer'
        option password 'your_api_token'
        option interface 'wan'
        option use_https '1'
        option cacert '/etc/ssl/certs'
        option use_api_check '1'        # ← Enable API-based IP verification
        option ip_source 'network'
        option ip_network 'wan'

Via UCI commands:

uci set ddns.cloudflare.use_api_check='1'
uci commit ddns
/etc/init.d/ddns restart

Note for Other Providers: This feature is built into the ddns-scripts framework. Other DNS providers with proxy or CDN features (like DigitalOcean, Route53, etc.) can implement API-based IP verification by adding GET_REGISTERED_IP support to their provider scripts. If you're a provider script maintainer, see the Cloudflare implementation in /usr/lib/ddns/update_cloudflare_com_v4.sh as a reference.

For maximum performance and reliability, you can pre-specify the zone ID and DNS record ID. This skips the auto-detection process and goes directly to your specific record.

Finding your IDs:

Method 1: Cloudflare Dashboard

1. Go to your domain's DNS management page
2. Click on the A record you want to update
3. In the URL, you'll see the record ID
4. Zone ID is shown on the domain overview page (right sidebar)

Method 2: Using the API

# Get Zone ID
curl -X GET "https://api.cloudflare.com/client/v4/zones?name=example.com" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json"
 
# Get DNS Record ID (replace ZONE_ID)
curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records?name=home.example.com&type=A" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json"

Adding to your configuration:

option param_opt 'zone_id=abc1234567890 dns_record_id=def9876543210'

Complete example:

# /etc/config/ddns
config service 'cloudflare'
        option service_name 'cloudflare.com-v4'
        option enabled '1'
        option domain 'home@example.com'
        option username 'Bearer'
        option password 'your_api_token'
        option param_opt 'zone_id=abc123 dns_record_id=def456'
        option interface 'wan'
        option use_https '1'
        option cacert '/etc/ssl/certs'

To update multiple subdomains, create a separate service configuration for each one:

# First subdomain
config service 'cloudflare_home'
        option service_name 'cloudflare.com-v4'
        option enabled '1'
        option domain 'home@example.com'
        option username 'Bearer'
        option password 'your_api_token'
        option interface 'wan'
 
# Second subdomain
config service 'cloudflare_vpn'
        option service_name 'cloudflare.com-v4'
        option enabled '1'
        option domain 'vpn@example.com'
        option username 'Bearer'
        option password 'your_api_token'
        option interface 'wan'

Note: You can use the same API token for multiple records if the token has access to all necessary zones.

Problem: Logs show “Update needed” on every check, even though your IP hasn't changed.

Symptoms - DNS Mode (use_api_check='0' or unset):

Detect registered/public IP
#> /usr/bin/nslookup home.example.com >/var/run/ddns/cloudflare.dat
Registered IP '104.21.x.x' detected    ← This is Cloudflare's proxy IP
Local IP '1.2.3.4' detected
Update needed - L: '1.2.3.4' <> R: '104.21.x.x'

What Success Looks Like - API Mode (use_api_check='1'):

Using provider API for registered IP check via '/usr/lib/ddns/update_cloudflare_com_v4.sh'
Registered IP '1.2.3.4' detected via Cloudflare API    ← Real IP retrieved!
Local IP '1.2.3.4' detected
IPv4 at CloudFlare.com already up to date

What Fallback Looks Like (if API fails):

API check failed (error: '127') - falling back to DNS lookup
#> /usr/bin/nslookup home.example.com
Registered IP '1.2.3.4' detected    ← Falls back to DNS

Solution 1: Enable API-based verification (recommended if you need the proxy)

uci set ddns.cloudflare.use_api_check='1'
uci commit ddns
/etc/init.d/ddns restart

Note: If the API query fails for any reason, the script automatically falls back to DNS lookup, so this is safe to enable.

Solution 2: Disable Cloudflare proxy for this record

1. Go to Cloudflare DNS settings
2. Find your A record
3. Click the orange cloud icon to turn it gray (DNS only)
4. The script will now see your actual IP via DNS

Error: curl: (77) error setting certificate verify locations

Solution:

opkg update
opkg install ca-certificates
uci set ddns.cloudflare.cacert='/etc/ssl/certs'
uci commit ddns
/etc/init.d/ddns restart

Error: Cloudflare reported an error: “Invalid API Token”

Check:

1. Is username set to Bearer (case-sensitive)?
2. Is your API token correct and not expired?
3. Does the token have “Zone DNS Edit” permission?
4. Is the token scoped to the correct zone?

Error: Could not detect 'zone id' for domain.tld

Possible causes:

1. Domain not added to your Cloudflare account
2. API token doesn't have access to this zone
3. Typo in domain name

Error: Could not detect 'record id' for host.domain.tld

Solution:

1. Verify the A record exists in Cloudflare DNS settings
2. Check the domain format (should be subdomain@zone)
3. Ensure you're looking for the correct record type (A for IPv4, AAAA for IPv6)

Test manually before enabling:

# Stop the service
/etc/init.d/ddns stop
 
# Run manually with verbose output (replace 'cloudflare' with your service name)
/usr/lib/ddns/dynamic_dns_updater.sh cloudflare 1
 
# Check the output for errors
# If successful, enable the service
/etc/init.d/ddns start
/etc/init.d/ddns enable

If you enabled use_api_check, verify it's actually using the API:

Check log output for these messages:

# View the log file
cat /var/log/ddns/cloudflare*.log

Look for:

Using provider API for registered IP check via '/usr/lib/ddns/update_cloudflare_com_v4.sh'
Registered IP 'x.x.x.x' detected via Cloudflare API

If you see “detected via Cloudflare API“ - API mode is working!

If you see “detected via DNS lookup” - Still using DNS (check use_api_check setting)

If you see “API check failed... falling back” - API error, but fallback working (check credentials and connectivity)

Additional options you can set:

option check_interval '10'      # Check every 10 minutes
option force_interval '72'      # Force update every 72 hours
option retry_interval '60'      # Retry after 60 seconds on error
option retry_count '5'          # Retry 5 times before giving up
option use_syslog '2'           # Log to syslog (2 = warnings and errors)
option use_logfile '1'          # Enable log file

• DDNS client configuration guide
• SSL/TLS configuration
• Debugging DDNS issues
• Cloudflare API Documentation
• Script source code

Q: Can I use Cloudflare's proxy (orange cloud) with DDNS?

A: Yes! Enable API-based IP verification (use_api_check='1') to prevent false “update needed” detections. The script automatically falls back to DNS lookup if the API query fails, so it's safe to enable.

Q: What happens if the API verification fails?

A: The script gracefully falls back to DNS lookup. This means even if Cloudflare's API is temporarily unavailable, your DDNS updates will continue to work using the standard DNS method.

Q: Which is better: API Token or Global API Key?

A: API Token is significantly better. It's more secure (scoped permissions) and you can revoke it without changing your account password.

Q: Do I need to install additional packages?

A: Yes, you need ddns-scripts-cloudflare and ca-certificates (or ca-bundle) for SSL support.

Q: Can I update multiple domains/subdomains?

A: Yes, create a separate service configuration for each domain or subdomain you want to update.

Q: My update works but Cloudflare shows the proxy is disabled (gray cloud)

A: This is normal. The script does not change the proxy status. Set it manually in Cloudflare's dashboard.

Q: How often does the script check/update?

A: By default, it checks every 10 minutes (check_interval) and forces an update every 72 hours (force_interval).