Charon/docs/guides/dns-providers/cloudflare.md

Cloudflare DNS Provider Setup

Overview

Cloudflare is one of the most popular DNS providers and offers a free tier with API access. This guide walks you through setting up Cloudflare as a DNS provider in Charon for wildcard certificate support.

Prerequisites

• Active Cloudflare account (free tier is sufficient)
• Domain added to Cloudflare with nameservers configured
• Domain status: Active (not pending nameserver update)

Step 1: Generate API Token

Cloudflare API Tokens provide scoped access and are more secure than Global API Keys.

1. Log in to Cloudflare Dashboard
2. Click on your profile icon (top right) → My Profile
3. Select API Tokens from the left sidebar
4. Click Create Token
5. Use the Edit zone DNS template or create a custom token
6. Configure token permissions:
   • Permissions:
     • Zone → DNS → Edit
   • Zone Resources:
     • Include → Specific zone → Select your domain
     • OR Include → All zones (if managing multiple domains)
7. (Optional) Set Client IP Address Filtering for additional security
8. (Optional) Set TTL for token expiration
9. Click Continue to summary
10. Review permissions and click Create Token
11. Copy the token immediately (shown only once)

Tip: Store the API token in a password manager. Cloudflare won't display it again.

Step 2: Configure in Charon

1. Navigate to DNS Providers in Charon
2. Click Add Provider
3. Fill in the form:
   • Provider Type: Select Cloudflare
   • Name: Enter a descriptive name (e.g., "Cloudflare Production")
   • API Token: Paste the token from Step 1

Advanced Settings (Optional)

Expand Advanced Settings to customize:

• Propagation Timeout: 60 seconds (Cloudflare has fast global propagation)
• Polling Interval: 10 seconds (default)
• Set as Default: Enable if this is your primary DNS provider

Step 3: Test Connection

1. Click Test Connection button
2. Wait for validation (usually 2-5 seconds)
3. Verify you see: ✅ Connection successful

If the test fails, see Troubleshooting below.

Step 4: Save Configuration

Click Save to store the DNS provider configuration. Credentials are encrypted at rest using AES-256-GCM.

Step 5: Use with Wildcard Certificates

When creating a proxy host with a wildcard domain:

1. Navigate to Proxy Hosts → Add Proxy Host
2. Enter a wildcard domain: *.example.com
3. Select Cloudflare from the DNS Provider dropdown
4. Configure remaining settings
5. Save

Charon will automatically obtain a wildcard certificate using DNS-01 challenge.

Example Configuration

Provider Type: cloudflare
Name: Cloudflare - example.com
API Token: ********************************
Propagation Timeout: 60 seconds
Polling Interval: 10 seconds
Default: Yes

Required Permissions

The API token needs the following Cloudflare permissions:

• Zone → DNS → Edit: Create and delete TXT records for ACME challenges

Note: The token does NOT need Zone → Edit or Account-level permissions.

Troubleshooting

Connection Test Fails

Error: Invalid API token

• Verify the token was copied correctly (no extra spaces)
• Ensure the token has Zone → DNS → Edit permission
• Check token hasn't expired (if TTL was set)
• Regenerate the token if necessary

Error: Zone not found

• Verify the domain is added to your Cloudflare account
• Ensure domain status is Active (nameservers updated)
• Check API token includes the correct zone in Zone Resources

Certificate Issuance Fails

Error: DNS propagation timeout

• Cloudflare typically propagates in <30 seconds
• Check Cloudflare Status page for service issues
• Verify DNSSEC is configured correctly (if enabled)
• Try increasing Propagation Timeout to 120 seconds

Error: Unauthorized to edit DNS

• API token may have been revoked
• Regenerate a new token with correct permissions
• Update configuration in Charon

Rate Limiting

Cloudflare has generous API rate limits:

• Free plan: 1,200 requests per 5 minutes
• Certificate challenges typically use <10 requests

If you hit limits:

• Reduce polling frequency
• Avoid unnecessary test connection attempts
• Consider upgrading Cloudflare plan

Security Recommendations

1. Scope Tokens: Limit to specific zones rather than "All zones"
2. IP Filtering: Add your server's IP to Client IP Address Filtering
3. Set Expiration: Use token TTL for automatic expiration (renew before expiry)
4. Rotate Regularly: Generate new tokens every 90-180 days
5. Monitor Usage: Review API token activity in Cloudflare dashboard

Additional Resources

• Cloudflare API Documentation
• API Token Permissions
• Caddy Cloudflare Module
• Cloudflare Status Page

Related Documentation

• DNS Providers Overview
• Wildcard Certificates Guide
• DNS Challenges Troubleshooting