Compatibility:
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:
ddns-scripts-cloudflare installedCloudflare supports two authentication methods. Use API Tokens unless you have a specific reason to use the legacy method.
| Method | Security | Setup Difficulty | Recommended For |
|---|---|---|---|
| API Token | High (scoped permissions) | Easy | Everyone - this is the modern standard |
| Global API Key | Medium (full account access) | Very Easy | Legacy setups only |
API Tokens provide secure, scoped access to your Cloudflare account. This is the recommended authentication method.
Via LuCI (Web Interface):
Navigate to Services → Dynamic DNS → Edit your service
cloudflare.com-v4subdomain.example.com (your full domain name)subdomain@example.com (use @ symbol to separate subdomain from domain)Bearer (exactly as shown, case-sensitive)wan for IPv4/A record, or wan6 for IPv6/AAAA)/etc/ssl/certsVia 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.
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:
| Your DNS Record | domain Parameter | Notes |
|---|---|---|
example.com |
example.com or @example.com |
Updates the apex/root domain A record |
www.example.com |
www@example.com |
Updates the www subdomain |
home.example.com |
home@example.com |
Updates the home subdomain |
vpn.lab.example.com |
vpn.lab@example.com |
Updates a nested subdomain |
Format: subdomain@zone
example.com or @example.comWhat 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:
:!: Note: This is entirely optional. If you're not using Cloudflare's proxy (gray cloud ☁️), you don't need this feature.
How it works:
use_api_check='0' or unset: Uses DNS lookup (default behavior)use_api_check='1': Queries Cloudflare API for the registered IPHow 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
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
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:
username set to Bearer (case-sensitive)?Error: Could not detect 'zone id' for domain.tld
Possible causes:
Error: Could not detect 'record id' for host.domain.tld
Solution:
subdomain@zone)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
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).