Table of Contents
Using acme.sh with Cloudflare DNS Challenge is one of the most flexible and powerful ways to obtain free SSL certificates — especially for servers behind firewalls, those without open ports, or when you need Wildcard SSL covering all subdomains. This guide walks you from installation to a fully automated SSL setup.
1. What is acme.sh
acme.sh is a pure Unix shell implementation of the ACME protocol. It requires no Python, Ruby, or external dependencies, making it compatible with virtually any Linux, macOS, or Unix-like system. It supports over 150 DNS providers including Cloudflare, Route53, GoDaddy, and many more.
| Feature | acme.sh | Certbot |
|---|---|---|
| Language | Shell Script | Python |
| Dependencies | None | Python + pip packages |
| DNS Providers | 150+ | ~30 (via plugins) |
| Wildcard SSL | ✅ Supported | ✅ Supported |
| Auto-renewal | ✅ Cron Job | ✅ Systemd Timer |
| Non-root install | ✅ Yes | ❌ Requires root |
2. DNS Challenge vs HTTP Challenge
The ACME protocol offers two primary domain verification methods:
- HTTP-01 Challenge: Creates a file at
/.well-known/acme-challenge/on your server. Requires Port 80 to be open and publicly accessible. - DNS-01 Challenge: Adds a TXT record to your DNS. No open ports required. The only method supporting Wildcard SSL.
DNS-01 via Cloudflare is ideal when:
- Your server is behind a firewall or on a private network
- You need Wildcard SSL (
*.example.com) - Port 80 is blocked or in use by another service
- You need zero-downtime renewal automation
3. Prerequisites
- Linux server (Ubuntu, CentOS, Debian, etc.)
- Domain using Cloudflare as nameserver
- Free Cloudflare account
- Root or sudo access on the server
curlandopensslinstalled (usually pre-installed)
4. Installing acme.sh
Install acme.sh with a single command:
# Install from GitHub
curl https://get.acme.sh | sh -s [email protected]
# Alternative with wget
wget -O - https://get.acme.sh | sh -s [email protected]
The installer will:
- Create the
~/.acme.sh/directory - Add an
acme.shalias to your shell profile - Install a cron job for auto-renewal
# Reload shell alias
source ~/.bashrc
# Verify installation
acme.sh --version
Set Default CA to Let's Encrypt
acme.sh --set-default-ca --server letsencrypt
5. Setting up Cloudflare API Token
acme.sh supports two Cloudflare authentication methods:
Method 1: API Token (Recommended)
- Go to Cloudflare Dashboard → My Profile → API Tokens
- Click Create Token
- Select the Edit zone DNS template
- Zone Resources: Select specific zones or All zones
- Click Continue to summary → Create Token
- Save the token (shown only once)
export CF_Token="your_cloudflare_api_token"
export CF_Account_ID="your_cloudflare_account_id"
Method 2: Global API Key (Not Recommended)
export CF_Key="your_global_api_key"
export CF_Email="[email protected]"
6. Issuing SSL Certificate
Issue SSL for a single domain:
# Issue SSL for example.com (export CF_Token first)
acme.sh --issue --dns dns_cf \
--domain example.com \
--domain www.example.com
acme.sh will:
- Create a TXT record at
_acme-challenge.example.comvia Cloudflare API - Wait for DNS propagation (~10-30 seconds)
- Submit the challenge to Let's Encrypt / ZeroSSL
- Store the certificate in
~/.acme.sh/example.com/
# Issued certificate files
~/.acme.sh/example.com/
├── example.com.cer # Certificate
├── example.com.key # Private Key
├── ca.cer # CA Bundle
└── fullchain.cer # Certificate + Chain (most commonly used)
7. Issuing Wildcard SSL
Wildcard SSL covers *.example.com — all subdomains:
# Issue Wildcard SSL (DNS Challenge required)
acme.sh --issue --dns dns_cf \
--domain example.com \
--domain "*.example.com"
example.com and *.example.com because Wildcard does not automatically cover the root domain itself.
Multi-Domain SSL (SAN)
# SSL covering multiple domains
acme.sh --issue --dns dns_cf \
--domain example.com \
--domain www.example.com \
--domain api.example.com \
--domain app.example.com
8. Installing Certificate on Server
After issuance, deploy the certificate to your web server:
For Nginx
acme.sh --install-cert -d example.com \
--cert-file /etc/nginx/ssl/example.com.cer \
--key-file /etc/nginx/ssl/example.com.key \
--fullchain-file /etc/nginx/ssl/fullchain.cer \
--reloadcmd "systemctl reload nginx"
For Apache
acme.sh --install-cert -d example.com \
--cert-file /etc/apache2/ssl/example.com.cer \
--key-file /etc/apache2/ssl/example.com.key \
--fullchain-file /etc/apache2/ssl/fullchain.cer \
--reloadcmd "systemctl reload apache2"
Nginx Virtual Host Configuration
server {
listen 443 ssl;
server_name example.com www.example.com;
ssl_certificate /etc/nginx/ssl/fullchain.cer;
ssl_certificate_key /etc/nginx/ssl/example.com.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
}
--install-cert so acme.sh remembers the deployment paths and reload command for automatic renewal.
9. Automatic SSL Renewal
acme.sh installs a cron job automatically during installation. Verify it:
# Check acme.sh cron job
crontab -l | grep acme
Expected output:
0 0 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" > /dev/null
The cron job runs daily at midnight and renews any certificate expiring within 30 days. It automatically runs the --reloadcmd you specified during --install-cert.
Force Renew and Debug
# Force renew (for testing)
acme.sh --renew -d example.com --force
# List all certificates and status
acme.sh --list
# Debug mode
acme.sh --issue --dns dns_cf -d example.com --debug 2
# Staging mode (doesn't count against rate limits)
acme.sh --issue --dns dns_cf -d example.com --staging
10. Frequently Asked Questions
What is the difference between acme.sh and Certbot?
acme.sh is a pure shell script with no Python dependencies, supports 150+ DNS providers, and can be installed without root privileges. Certbot requires Python and needs additional plugins for DNS Challenge. For DNS-based workflows, acme.sh is generally simpler to set up.
How long does Cloudflare DNS Challenge take?
Typically 10-30 seconds. Cloudflare propagates TXT records very quickly. acme.sh waits 10 seconds after creating the record before verifying. For slower DNS providers, add --dnssleep 60 to increase the wait time.
What happens if my Cloudflare API Token expires or is revoked?
Auto-renewal will fail. Create a new token and update the environment variable, or save it permanently in ~/.acme.sh/account.conf as SAVED_CF_Token="..." so it persists across sessions.
Can I use acme.sh on shared hosting?
Yes, if you have SSH access and can create cron jobs. Most shared hosting environments have curl and openssl pre-installed. On DirectAdmin hosting with SSH access, acme.sh works out of the box.
Are Let's Encrypt SSL certificates trusted by all browsers?
Yes. Let's Encrypt and ZeroSSL certificates are trusted by all modern browsers and operating systems including Chrome, Firefox, Safari, Edge, Android 7.1+, and iOS 10+.
How is this different from getting SSL through AsiaGB's DirectAdmin?
AsiaGB's DirectAdmin hosting includes one-click Let's Encrypt SSL for hosted domains — no configuration needed. acme.sh + Cloudflare is best for VPS environments, Wildcard SSL requirements, or when you manage your DNS through Cloudflare separately from your hosting.
Summary
acme.sh + Cloudflare DNS Challenge provides:
- ✅ 100% Free SSL — via Let's Encrypt or ZeroSSL
- ✅ Wildcard SSL support — covers
*.example.comvia DNS Challenge - ✅ No open ports required — DNS-only verification
- ✅ Fully automatic renewal — cron job renews every 60 days
- ✅ Simple installation — pure shell script, zero dependencies
For AsiaGB Hosting and VPS customers needing basic SSL, Let's Encrypt is available directly from the DirectAdmin Control Panel. For Wildcard SSL or advanced use cases, acme.sh + Cloudflare is the best solution.