Charon/docs/features/dns-auto-detection.md

DNS Provider Auto-Detection

Overview

DNS Provider Auto-Detection is an intelligent feature that automatically identifies which DNS provider manages your domain's nameservers. This helps streamline the setup process and reduces configuration errors when creating wildcard SSL certificate proxy hosts.

Benefits

• Reduce Configuration Errors: Eliminates the risk of selecting the wrong DNS provider
• Faster Setup: No need to manually check your DNS registrar or control panel
• Auto-Fill Provider Selection: Automatically suggests the correct DNS provider in proxy host forms
• Reduced Support Burden: Fewer configuration issues to troubleshoot

When Detection Occurs

Auto-detection runs automatically when you:

• Enter a wildcard domain (*.example.com) in the proxy host creation form
• The domain requires DNS-01 challenge validation for Let's Encrypt SSL certificates

How Auto-Detection Works

Detection Process

1. Nameserver Lookup: System performs a DNS query to retrieve the authoritative nameservers for your domain
2. Pattern Matching: Compares nameserver hostnames against known provider patterns
3. Confidence Assessment: Assigns a confidence level based on match quality
4. Provider Suggestion: Suggests configured DNS providers that match the detected type
5. Caching: Results are cached for 1 hour to improve performance

Confidence Levels

Level	Description	Action Required
High	Exact match with known provider pattern	Safe to use auto-detected provider
Medium	Partial match or common pattern	Verify provider before using
Low	Weak match or ambiguous pattern	Manually verify provider selection
None	No matching pattern found	Manual provider selection required

Caching Behavior

• Detection results are cached for 1 hour
• Reduces DNS query load and improves response time
• Cache is invalidated when manually changing provider
• Each domain is cached independently

Using Auto-Detection

Automatic Detection

When creating a new proxy host with a wildcard domain:

1. Enter your wildcard domain in the Domain Names field (e.g., *.example.com)
2. The system automatically performs nameserver lookup
3. Detection results appear in the DNS Provider section
4. If a match is found, the provider is automatically selected

Visual Indicator: A detection status badge appears next to the DNS Provider dropdown showing:

• ✓ Provider detected
• ⚠ No provider detected
• ℹ Multiple nameservers found

Manual Detection

If auto-detection doesn't run automatically or you want to recheck:

1. Click the Detect Provider button next to the DNS Provider dropdown
2. System performs fresh nameserver lookup (bypasses cache)
3. Results update immediately

Note

: Manual detection is useful after changing nameservers at your DNS provider.

Reviewing Detection Results

The detection results panel displays:

Field	Description
Status	Whether provider was detected
Detected Provider Type	DNS provider identified (e.g., "cloudflare")
Confidence	Detection confidence level
Nameservers	List of authoritative nameservers found
Suggested Provider	Configured provider that matches detected type

Manual Override

You can always override auto-detection:

1. Select a different provider from the DNS Provider dropdown
2. Your selection takes precedence over auto-detection
3. System uses your selected provider credentials

Warning

: Using the wrong provider will cause SSL certificate issuance to fail.

Detection Results Explained

Example 1: Successful Detection

Domain: *.example.com

Detection Results:
✓ Provider Detected

Detected Provider Type: cloudflare
Confidence: High
Nameservers:
  - ns1.cloudflare.com
  - ns2.cloudflare.com

Suggested Provider: "Production Cloudflare"

Action: Use the suggested provider with confidence.

Example 2: No Match Found

Domain: *.internal.company.com

Detection Results:
⚠ No Provider Detected

Nameservers:
  - ns1.internal.company.com
  - ns2.internal.company.com

Confidence: None

Action: Manually select the appropriate DNS provider or configure a custom provider.

Example 3: Multiple Providers (Rare)

Domain: *.example.com

Detection Results:
⚠ Multiple Providers Detected

Detected Types:
  - cloudflare (2 nameservers)
  - route53 (1 nameserver)

Confidence: Medium

Action: Verify your domain's nameserver configuration at your DNS registrar. Mixed providers are uncommon and may indicate a configuration issue.

Supported DNS Providers

The system recognizes the following DNS providers by their nameserver patterns:

Provider	Nameserver Pattern	Example Nameserver
Cloudflare	*.ns.cloudflare.com	ns1.cloudflare.com
AWS Route 53	*.awsdns*	ns-123.awsdns-12.com
DigitalOcean	*.digitalocean.com	ns1.digitalocean.com
Google Cloud DNS	*.googledomains.com, ns-cloud*	ns-cloud-a1.googledomains.com
Azure DNS	*.azure-dns*	ns1-01.azure-dns.com
Namecheap	*.registrar-servers.com	dns1.registrar-servers.com
GoDaddy	*.domaincontrol.com	ns01.domaincontrol.com
Hetzner	*.hetzner.com, *.hetzner.de	helium.ns.hetzner.com
Vultr	*.vultr.com	ns1.vultr.com
DNSimple	*.dnsimple.com	ns1.dnsimple.com

Provider-Specific Examples

Cloudflare

Nameservers:
  ns1.cloudflare.com
  ns2.cloudflare.com

Detected: cloudflare (High confidence)

AWS Route 53

Nameservers:
  ns-1234.awsdns-12.com
  ns-5678.awsdns-34.net

Detected: route53 (High confidence)

Google Cloud DNS

Nameservers:
  ns-cloud-a1.googledomains.com
  ns-cloud-a2.googledomains.com

Detected: googleclouddns (High confidence)

DigitalOcean

Nameservers:
  ns1.digitalocean.com
  ns2.digitalocean.com
  ns3.digitalocean.com

Detected: digitalocean (High confidence)

Unsupported Providers

If your DNS provider isn't listed above:

1. Custom/Internal DNS: You'll need to manually select a provider that uses the same API (e.g., many providers use Cloudflare's API)
2. New Provider: Request support by opening a GitHub issue with your provider's nameserver pattern
3. Workaround: Configure a supported provider that's API-compatible, or use a different DNS provider for wildcard domains

Manual Override Scenarios

When to Override Auto-Detection

Override auto-detection when:

1. Multiple Credentials: You have multiple configured providers of the same type (e.g., "Dev Cloudflare" and "Prod Cloudflare")
2. API-Compatible Providers: Using a provider that shares an API with a detected provider
3. Custom DNS Servers: Running custom DNS infrastructure that mimics provider nameservers
4. Testing: Deliberately testing with different credentials

How to Override

1. Ignore the auto-detected provider suggestion
2. Select your preferred provider from the DNS Provider dropdown
3. Save the proxy host with your selection
4. System will use your selected credentials

Important

: Ensure your selected provider has valid API credentials and permissions to modify DNS records for the domain.

Custom Nameservers

For custom or internal nameservers:

1. Detection will likely return "No Provider Detected"
2. You must manually select a provider
3. Ensure the selected provider type matches your DNS server's API
4. Configure appropriate API credentials in the DNS Provider settings

Example:

Domain: *.corp.internal
Nameservers: ns1.corp.internal, ns2.corp.internal

Auto-detection: None
Manual selection required: Select compatible provider or configure custom

Troubleshooting

Detection Failed: Domain Not Found

Symptom: Error message "Failed to detect DNS provider" or "Domain not found"

Causes:

• Domain doesn't exist yet
• Domain not propagated to public DNS
• DNS resolution blocked by firewall

Solutions:

• Verify domain exists and is registered
• Wait for DNS propagation (up to 48 hours)
• Check network connectivity and DNS resolution
• Manually select provider and proceed

Wrong Provider Detected

Symptom: System detects incorrect provider type

Causes:

• Domain using DNS proxy/forwarding service
• Recent nameserver change not yet propagated
• Multiple providers in nameserver list

Solutions:

• Wait for DNS propagation (up to 24 hours)
• Manually override provider selection
• Verify nameservers at your domain registrar
• Use manual detection to refresh results

Multiple Providers Detected

Symptom: Detection shows multiple provider types

Causes:

• Nameservers from different providers (unusual)
• DNS migration in progress
• Misconfigured nameservers

Solutions:

• Check nameserver configuration at your registrar
• Complete DNS migration to single provider
• Manually select the primary/correct provider
• Contact DNS provider support if configuration is correct

No DNS Provider Configured for Detected Type

Symptom: Provider detected but no matching provider configured in system

Example:

Detected Provider Type: cloudflare
Error: No DNS provider of type 'cloudflare' is configured

Solutions:

1. Navigate to Settings → DNS Providers
2. Click Add DNS Provider
3. Select the detected provider type (e.g., Cloudflare)
4. Enter API credentials:
   • Cloudflare: API Token or Global API Key + Email
   • Route 53: Access Key ID + Secret Access Key
   • DigitalOcean: API Token
   • (See provider-specific documentation)
5. Save provider configuration
6. Return to proxy host creation and retry

Tip

: You can configure multiple providers of the same type with different names (e.g., "Dev Cloudflare" and "Prod Cloudflare").

Custom/Internal DNS Servers Not Detected

Symptom: Using private/internal DNS, no provider detected

This is expected behavior. Custom DNS servers don't match public provider patterns.

Solutions:

1. Manually select a provider that uses a compatible API
2. If using BIND, PowerDNS, or other custom DNS:
   • Configure acme.sh or certbot direct integration
   • Use supported provider API if available
   • Consider using supported DNS provider for wildcard domains only
3. If no compatible API:
   • Use HTTP-01 challenge instead (no wildcard support)
   • Configure manual DNS challenge workflow

Detection Caching Issues

Symptom: Detection results don't reflect recent nameserver changes

Cause: Results cached for 1 hour

Solutions:

• Wait up to 1 hour for cache to expire
• Use Detect Provider button for manual detection (bypasses cache)
• DNS propagation may also take additional time (separate from caching)

API Reference

Detection Endpoint

Auto-detection is exposed via REST API for automation and integrations.

Endpoint

POST /api/dns-providers/detect

Authentication

Requires API token with dns_providers:read permission.

Authorization: Bearer YOUR_API_TOKEN

Request Body

{
  "domain": "*.example.com"
}

Parameters:

• domain (required): Full domain name including wildcard (e.g., *.example.com)

Response: Success

{
  "status": "detected",
  "provider_type": "cloudflare",
  "confidence": "high",
  "nameservers": [
    "ns1.cloudflare.com",
    "ns2.cloudflare.com"
  ],
  "suggested_provider_id": 42,
  "suggested_provider_name": "Production Cloudflare",
  "cached": false
}

Response Fields:

• status: "detected" or "not_detected"
• provider_type: Detected provider type (string) or null
• confidence: "high", "medium", "low", or "none"
• nameservers: Array of authoritative nameservers (strings)
• suggested_provider_id: Database ID of matching configured provider (integer or null)
• suggested_provider_name: Display name of matching provider (string or null)
• cached: Whether result is from cache (boolean)

Response: Not Detected

{
  "status": "not_detected",
  "provider_type": null,
  "confidence": "none",
  "nameservers": [
    "ns1.custom-dns.com",
    "ns2.custom-dns.com"
  ],
  "suggested_provider_id": null,
  "suggested_provider_name": null,
  "cached": false
}

Response: Error

{
  "error": "Failed to resolve nameservers for domain",
  "details": "NXDOMAIN: domain does not exist"
}

HTTP Status Codes:

• 200 OK: Detection completed successfully
• 400 Bad Request: Invalid domain format
• 401 Unauthorized: Missing or invalid API token
• 500 Internal Server Error: DNS resolution or server error

Example: cURL

curl -X POST https://charon.example.com/api/dns-providers/detect \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "*.example.com"
  }'

Example: JavaScript

async function detectDNSProvider(domain) {
  const response = await fetch('/api/dns-providers/detect', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain })
  });

  const result = await response.json();

  if (result.status === 'detected') {
    console.log(`Detected: ${result.provider_type} (${result.confidence})`);
    console.log(`Nameservers: ${result.nameservers.join(', ')}`);
  } else {
    console.log('No provider detected');
  }

  return result;
}

// Usage
detectDNSProvider('*.example.com');

Example: Python

import requests

def detect_dns_provider(domain: str, api_token: str) -> dict:
    response = requests.post(
        'https://charon.example.com/api/dns-providers/detect',
        headers={
            'Authorization': f'Bearer {api_token}',
            'Content-Type': 'application/json'
        },
        json={'domain': domain}
    )
    response.raise_for_status()
    return response.json()

# Usage
result = detect_dns_provider('*.example.com', 'YOUR_API_TOKEN')
if result['status'] == 'detected':
    print(f"Detected: {result['provider_type']} ({result['confidence']})")
    print(f"Nameservers: {', '.join(result['nameservers'])}")
else:
    print('No provider detected')

Best Practices

General Recommendations

1. Trust High Confidence: High-confidence detections are highly reliable
2. Verify Medium/Low: Always verify medium or low confidence detections before using
3. Manual Override When Needed: Don't hesitate to override if detection seems incorrect
4. Keep Providers Updated: Ensure DNS provider API credentials are current
5. Monitor Detection: Track detection success rates in your environment

For Multiple Environments

When managing multiple environments (dev, staging, production):

1. Use descriptive provider names: "Dev Cloudflare", "Prod Cloudflare"
2. Auto-detection will suggest the first matching provider by default
3. Always verify the suggested provider matches your intended environment
4. Consider using different DNS providers per environment to avoid confusion

For Enterprise/Internal DNS

If using custom enterprise DNS infrastructure:

1. Document which Charon DNS provider type is compatible with your system
2. Create named providers for each environment/purpose
3. Train users to ignore auto-detection for internal domains
4. Consider maintaining a mapping document of internal domains to correct providers

For Multi-Credential Setups

When using multiple credentials for the same provider:

1. Name providers clearly: "Cloudflare - Account A", "Cloudflare - Account B"
2. Document which domains belong to which account
3. Always review auto-detected suggestions carefully
4. Use manual override to select the correct credential set

Related Documentation

• DNS Provider Configuration - Setting up DNS provider credentials
• Multi-Credential DNS Support - Managing multiple providers of same type
• Proxy Host Creation - Creating wildcard SSL proxy hosts
• SSL Certificate Management - Let's Encrypt and certificate issuance
• Troubleshooting DNS Issues - Common DNS configuration problems

Support

If you encounter issues with DNS Provider Auto-Detection:

1. Check the Troubleshooting section above
2. Review GitHub Issues for similar problems
3. Open a new issue with:
   • Domain name (sanitized if sensitive)
   • Detected provider (if any)
   • Expected provider
   • Nameservers returned
   • Error messages or logs

---

Last Updated: January 2026 Feature Version: 0.1.6-beta.0+ Status: Production Ready