RWTS ACME DNS Documentation

RWTS ACME DNS is a centralized DNS-01 challenge service that allows you to obtain SSL/TLS certificates for domains without exposing your internal DNS infrastructure. This is particularly useful for:

• Internal services - Get certificates for services not exposed to the internet
• Wildcard certificates - DNS-01 is required for wildcard certificates
• Automation - Centralized certificate management across multiple systems
• Security - No need to expose internal DNS servers

How It Works

1. Register your domain with our service using your API key
2. Add a CNAME record pointing to our DNS server
3. Configure your ACME client to use our service
4. Request certificates - the challenges are handled automatically

API keys are required to use this service and must be obtained from your system administrator. Each API key:

• Is unique to your organization or project
• Has usage tracking and rate limiting
• May have an expiration date
• Can be revoked if compromised

Using the Web Interface

1. Go to the main page
2. Select "Register New Domain"
3. Enter your API key and domain name
4. Click "Register Domain"
5. Download the configuration files provided

Using the API Directly

curl -X POST https://acmedns.realworld.net.au/api/register \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

The response will include:

• subdomain - Your unique subdomain for challenges
• username/password - Credentials for ACME client configuration
• fulldomain - The full domain for ACME clients

After registering your domain, you need to add a CNAME record to your DNS. This tells the ACME service where to find your domain's challenge responses.

CNAME Record Format

Examples

If you've already registered a domain and need to retrieve the configuration:

Using the Web Interface

1. Go to the main page
2. Select "Look Up Configuration"
3. Enter your API key and domain name
4. View and download your configuration

Using the API

curl -X POST https://acmedns.realworld.net.au/api/lookup \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

Installation

# Install certbot and acme-dns plugin
pip install certbot certbot-dns-acmedns

Configuration

Create /etc/acmedns.ini with your credentials:

dns_acmedns_api_url = https://acmedns.realworld.net.au
dns_acmedns_registration_file = /etc/acmedns-registration.json

Create /etc/acmedns-registration.json with your domain registration:

{
  "example.com": {
    "username": "your-username",
    "password": "your-password",
    "fulldomain": "your-subdomain.acmedns.realworld.net.au",
    "subdomain": "your-subdomain",
    "allowfrom": []
  }
}

Usage

# Get a certificate
certbot certonly \
  --dns-acmedns \
  --dns-acmedns-credentials /etc/acmedns.ini \
  -d example.com

# Get a wildcard certificate
certbot certonly \
  --dns-acmedns \
  --dns-acmedns-credentials /etc/acmedns.ini \
  -d "*.example.com" -d example.com

Installation

curl https://get.acme.sh | sh

Configuration

Set up environment variables with your ACME DNS credentials:

export ACMEDNS_BASE_URL="https://acmedns.realworld.net.au"
export ACMEDNS_USERNAME="your-username"
export ACMEDNS_PASSWORD="your-password" 
export ACMEDNS_SUBDOMAIN="your-subdomain"

Usage

# Get a certificate
acme.sh --issue --dns dns_acmedns -d example.com

# Get a wildcard certificate
acme.sh --issue --dns dns_acmedns -d "*.example.com" -d example.com

Installation

# Download from https://github.com/go-acme/lego/releases
# Or install with Go:
go install github.com/go-acme/lego/v4/cmd/lego@latest

Configuration

Set environment variables:

export ACME_DNS_API_BASE="https://acmedns.realworld.net.au"
export ACME_DNS_STORAGE_PATH="/path/to/acmedns-registration.json"

Usage

# Get a certificate
lego --dns acme-dns --domains example.com --email you@example.com run

# Get a wildcard certificate  
lego --dns acme-dns --domains "*.example.com" --email you@example.com run

Available Endpoints

Rate Limits

• Domain Registration: 10 per minute
• Config Lookup: 20 per minute
• Key Info: 30 per minute
• Overall: 50 per hour, 200 per day

Common Issues

Getting Help

If you continue to experience issues:

1. Check the service status at the health endpoint
2. Review your API key information at the main interface
3. Contact your system administrator with specific error messages
4. Include your domain name and API key ID (not the full key) when reporting issues

Security

• Protect your API key - Store securely, don't commit to repositories
• Use appropriate file permissions - 600 for credential files
• Rotate keys regularly - Contact admin for key rotation
• Monitor usage - Check your key info regularly for unexpected usage

Automation

• Use systemd timers or cron - For automatic certificate renewal
• Implement proper error handling - Log failures and alert on issues
• Test renewals - Use --dry-run flags to test configurations
• Monitor expiration - Set up alerts for certificate expiration

Performance

• Respect rate limits - Don't exceed API limits
• Cache registrations - Only register domains once
• Use wildcard certificates - When appropriate for multiple subdomains
• Plan renewals - Spread renewal times to avoid rate limits