Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve cloudflare docs #964

Closed
wants to merge 2 commits into from

Conversation

aollivierre
Copy link

@aollivierre aollivierre commented Mar 20, 2025

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:
"domain": "example.com", "host": "subdomain"

Rather than using a single field like:

"domain": "subdomain.example.com"
  1. Using API Token authentication rather than Global API Key
  2. 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.

@aollivierre aollivierre deleted the improve-cloudflare-docs branch March 20, 2025 15:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant