Hi everyone,
I'm excited to share a major update to the Cloudflare DDNS documentation and a new feature that solves a long-standing issue with Cloudflare's proxy (orange cloud 
) functionality.
For Other Provider Developers
This is implemented at the framework level in dynamic_dns_functions.sh. Other DNS providers with proxy/CDN features can implement API-based IP verification by adding GET_REGISTERED_IP mode support to their provider scripts.
The Problem
Many users have experienced an issue where their DDNS client constantly thinks an update is needed, even when their IP hasn't changed. This happens because:
- When Cloudflare's proxy is enabled (orange cloud ), DNS lookups return Cloudflare's edge server IPs
- The DDNS script compares this proxy IP to your actual router IP
- They don't match, so it tries to update on every check
- This wastes API calls and fills logs with false "Update needed" messages
The Solution
New in ddns-scripts 2.8.2-93: API-based registered IP verification via use_api_check option.
When enabled, the script queries Cloudflare's API directly to get your actual registered IP, bypassing DNS entirely. This gives you the real IP even when the proxy is enabled.
Key features:
Solves the orange cloud proxy IP problem- Gracefully falls back to DNS if API query fails
- Framework-level feature (other providers can implement it too)
- Completely optional (default behavior unchanged)
- Safe to enable (automatic fallback)
How to Use It
Simple setup:
- Configure Cloudflare DDNS as normal (using API Token)
- Add one option to enable API verification:
uci set ddns.your_service.use_api_check='1'
uci commit ddns
/etc/init.d/ddns restart
Example configuration:
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' # ← New option
What it looks like in logs:
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
IPv4 at CloudFlare.com already up to date
Updated Documentation
The Cloudflare section of the DDNS wiki has been completely rewritten with:
Step-by-step setup for API Tokens (recommended) and Global API Key
Complete documentation of the new API verification feature
Real log output examples for all scenarios
Comprehensive troubleshooting guide (including the orange cloud problem)- Testing and verification instructions
FAQ section covering common questions
Read the full documentation here:
Requirements
- OpenWrt: 22.03 and newer, SNAPSHOT
- Package: ddns-scripts 2.8.2-93 or newer
- Install:
opkg install ddns-scripts-cloudflare ca-certificates
When to Use This
You should enable use_api_check='1' 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
You don't need it if:
- Your Cloudflare DNS record is set to "DNS only" (gray cloud
) - You're not experiencing the false update problem
See the Cloudflare implementation in /usr/lib/ddns/update_cloudflare_com_v4.sh as a reference (lines 247-263).
Backward Compatibility
- Existing configurations continue to work without changes
- Default behavior is unchanged (DNS lookup)
-
use_api_checkis completely optional - Safe to upgrade
The framework-level design means other providers can easily add this capability too.
Feedback Welcome
If you've been experiencing the orange cloud problem, please try this feature and let me know how it works for you!
Questions, suggestions, or issues? Reply below or check the wiki documentation.
Useful Links:
- Full documentation: https://openwrt.org/docs/guide-user/services/ddns/client#cloudflarecom
- Source code: https://github.com/openwrt/packages/tree/master/net/ddns-scripts
- General DDNS help: https://openwrt.org/docs/guide-user/base-system/ddns
Enjoy!