[PR #965] Improve Cloudflare documentation with verified configuration approach #921

New Issue

saavagebueno · 2025-11-20T04:26:32-05:00

saavagebueno commented

2025-11-20 04:26:32 -05:00

📋 Pull Request Information

Original PR: https://github.com/qdm12/ddns-updater/pull/965
Author: @aollivierre
Created: 3/20/2025
Status: 🔄 Open

Base: master ← Head: cloudflare-docs-fix

📝 Commits (1)

bb33cfe Improve Cloudflare documentation with verified configuration approach

📊 Changes

1 file changed (+254 additions, -24 deletions)

View changed files

📝 docs/cloudflare.md (+254 -24)

📄 Description

Pull Request Description: Improved Cloudflare Documentation with Verified Configuration

Authentication Issues Encountered

We experienced persistent Cloudflare authentication failures with DDNS-Updater, particularly after ISP modem restarts resulting in IP changes. Specifically:

The most common error was: "Missing X-Auth-Key, X-Auth-Email or Authorization headers" (Code 9106)
Even with correct API Tokens, authentication would sometimes fail after network interruptions
The container would be unable to update DNS records, requiring manual intervention
Domain records were sometimes reported as "DNS name is invalid" despite being correct

How Our Approach Resolves These Issues

After extensive testing, we identified a specific configuration pattern that reliably resolves these issues:

Using the config.json file with a mounted volume for persistence (instead of environment variables)
Critical: Splitting the domain into separate "domain" and "host" fields:

"domain": "example.com", "host": "subdomain"

Rather than using a single field like:

"domain": "subdomain.example.com"

Using API Token authentication rather than Global API Key
Ensuring proper TTL values are specified

Verification and Testing

We've rigorously tested this approach through multiple scenarios:

Confirmed working with both the latest container version and v2.5.0
Tested through multiple ISP modem restarts and IP changes
Verified long-term stability with this configuration
Tested with various Cloudflare-managed domains

Critical Elements for Success

Our documentation emphasizes these essential elements:

Domain/Host Splitting: Separating the domain into root domain and subdomain components
API Token Authentication: Using the more secure and reliable token-based authentication
Persistence with Mounted Volume: Ensuring configuration persists across container restarts
File Path Clarity: Documenting the exact file locations on both host and container
Comprehensive Troubleshooting: Addressing the most common errors with specific solutions

This pull request aims to help users avoid the frustrating authentication issues we encountered by documenting a proven, verified approach that works reliably in real-world conditions.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/qdm12/ddns-updater/pull/965 **Author:** [@aollivierre](https://github.com/aollivierre) **Created:** 3/20/2025 **Status:** 🔄 Open **Base:** `master` ← **Head:** `cloudflare-docs-fix` --- ### 📝 Commits (1) - [`bb33cfe`](https://github.com/qdm12/ddns-updater/commit/bb33cfe814ce4c8c5b46711de888a71d592c5160) Improve Cloudflare documentation with verified configuration approach ### 📊 Changes **1 file changed** (+254 additions, -24 deletions) <details> <summary>View changed files</summary> 📝 `docs/cloudflare.md` (+254 -24) </details> ### 📄 Description **Pull Request Description: Improved Cloudflare Documentation with Verified Configuration** **Authentication Issues Encountered** We experienced persistent Cloudflare authentication failures with DDNS-Updater, particularly after ISP modem restarts resulting in IP changes. Specifically: 1. The most common error was: **"Missing X-Auth-Key, X-Auth-Email or Authorization headers" (Code 9106)** 2. Even with correct API Tokens, authentication would sometimes fail after network interruptions 3. The container would be unable to update DNS records, requiring manual intervention 4. Domain records were sometimes reported as "DNS name is invalid" despite being correct **How Our Approach Resolves These Issues** After extensive testing, we identified a specific configuration pattern that reliably resolves these issues: 1. Using the `config.json` file with a mounted volume for persistence (instead of environment variables) 2. **Critical**: Splitting the domain into separate "domain" and "host" fields: ```json "domain": "example.com", "host": "subdomain" ``` Rather than using a single field like: ```json "domain": "subdomain.example.com" ``` 3. Using API Token authentication rather than Global API Key 4. Ensuring proper TTL values are specified **Verification and Testing** We've rigorously tested this approach through multiple scenarios: 1. Confirmed working with **both the latest container version and v2.5.0** 2. Tested through multiple ISP modem restarts and IP changes 3. Verified long-term stability with this configuration 4. Tested with various Cloudflare-managed domains **Critical Elements for Success** Our documentation emphasizes these essential elements: 1. **Domain/Host Splitting**: Separating the domain into root domain and subdomain components 2. **API Token Authentication**: Using the more secure and reliable token-based authentication 3. **Persistence with Mounted Volume**: Ensuring configuration persists across container restarts 4. **File Path Clarity**: Documenting the exact file locations on both host and container 5. **Comprehensive Troubleshooting**: Addressing the most common errors with specific solutions This pull request aims to help users avoid the frustrating authentication issues we encountered by documenting a proven, verified approach that works reliably in real-world conditions. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

saavagebueno added the pull-request label 2025-11-20 04:26:32 -05:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/ddns-updater#921