How to Use the Command 'acme.sh --dns' (with Examples)

The acme.sh tool is a powerful and flexible shell script that automates the process of obtaining a TLS/SSL certificate from Let’s Encrypt, an open Certificate Authority (CA) that offers free digital certificates. This command, specifically with the --dns option, is utilized to prove domain ownership via a DNS-01 challenge, which involves adding a specific DNS record to the domain’s DNS settings. This method is especially advantageous for automating the issuance of SSL certificates in a variety of situations such as wildcard certificates, multiple domains, or when using specific DNS providers or alias methods.

Use Case 1: Issue a Certificate Using an Automatic DNS API Mode

Code:

acme.sh --issue --dns gnd_gd --domain example.com

Motivation: This command is used when you need to issue a certificate for example.com and you have access to the domain’s DNS provider that supports an automatic API. The automatic DNS API mode is convenient as it eliminates the need for manual intervention by automating the entire process of updating DNS records.

Explanation:

• --issue: This flag initiates the certificate issuing process.
• --dns gnd_gd: Specifies the use of the automatic DNS API provided by the GoDaddy domain registrar (gnd_gd is short for GoDaddy).
• --domain example.com: Indicates the domain name for which the certificate is being issued.

Example Output:
The output may show the progress of the certificate issuance, confirming challenge completion and certificate download:

[Fri Oct 8 12:00:00 UTC 2021] Registering account
[Fri Oct 8 12:00:02 UTC 2021] Creating order for domains
[Fri Oct 8 12:00:04 UTC 2021] Using automatic DNS detection
[Fri Oct 8 12:00:06 UTC 2021] Verified domain 'example.com'
[Fri Oct 8 12:00:08 UTC 2021] Installing certificate to: /etc/ssl/example.com/
[Fri Oct 8 12:00:08 UTC 2021] Certificate successfully issued

Use Case 2: Issue a Wildcard Certificate Using an Automatic DNS API Mode

Code:

acme.sh --issue --dns dns_namesilo --domain example.com --domain *.example.com

Motivation: Wildcard certificates allow you to secure unlimited subdomains for a single domain (e.g., *.example.com). This use case is crucial when managing multiple subdomains as it simplifies certificate management and reduces overhead.

Explanation:

• --issue: Starts the certificate issuance process.
• --dns dns_namesilo: Uses the NameSilo DNS API to perform DNS operations automatically.
• --domain example.com: The primary domain for the certificate.
• --domain *.example.com: Specifies the wildcard for all subdomains under example.com.

Example Output:

[Fri Oct 8 12:15:00 UTC 2021] Registering account
[Fri Oct 8 12:15:03 UTC 2021] Creating wildcard domain order
[Fri Oct 8 12:15:05 UTC 2021] Using DNS API: dns_namesilo
[Fri Oct 8 12:15:10 UTC 2021] Wildcard domain verified: *.example.com
[Fri Oct 8 12:15:13 UTC 2021] Installing wildcard certificate
[Fri Oct 8 12:15:13 UTC 2021] Wildcard certificate issued successfully

Use Case 3: Issue a Certificate Using a DNS Alias Mode

Code:

acme.sh --issue --dns dns_cf --domain example.com --challenge-alias alias-for-example-validation.com

Motivation: The DNS Alias mode is beneficial when DNS changes are faster or more reliable for a different domain. This can happen in scenarios where the actual domain’s DNS provider has longer propagation delays or other issues.

Explanation:

• --issue: Triggers the certificate issuance.
• --dns dns_cf: Designates Cloudflare as the DNS provider for automatic updates.
• --domain example.com: The legitimate domain needing a certificate.
• --challenge-alias alias-for-example-validation.com: Utilizes alias-for-example-validation.com for validation purposes instead of example.com.

Example Output:

[Fri Oct 8 12:30:00 UTC 2021] Creating certificate order for domain alias
[Fri Oct 8 12:30:02 UTC 2021] Using provided DNS Alias
[Fri Oct 8 12:30:05 UTC 2021] Alias domain verified successfully
[Fri Oct 8 12:30:08 UTC 2021] Certificate for example.com installed
[Fri Oct 8 12:30:08 UTC 2021] Certificate issued and saved

Use Case 4: Issue a Certificate with Specified DNS Sleep Time

Code:

acme.sh --issue --dns dns_namecheap --domain example.com --dnssleep 300

Motivation: Specifying a custom DNS sleep time is helpful when you’re aware of the average DNS propagation delay for your provider. By setting an appropriate wait time, certificate issuance scripts might avoid unnecessary polling, which can expedite the process in some cases.

Explanation:

• --issue: Initiates the process of obtaining the certificate.
• --dns dns_namecheap: Engages Namecheap’s DNS API for automating DNS challenges.
• --domain example.com: Specifies the domain of interest.
• --dnssleep 300: Instructs acme.sh to wait 300 seconds (5 minutes) before verifying the DNS challenge.

Example Output:

[Fri Oct 8 12:45:00 UTC 2021] Starting DNS challenge verification
[Fri Oct 8 12:45:00 UTC 2021] Waiting 300 seconds for record propagation
[Fri Oct 8 12:50:00 UTC 2021] Verification successful
[Fri Oct 8 12:50:08 UTC 2021] Successfully issued certificate for example.com

Use Case 5: Issue a Certificate Using Manual DNS Mode

Code:

acme.sh --issue --dns --domain example.com --yes-I-know-dns-manual-mode-enough-go-ahead-please

Motivation: Manual DNS mode is deployed when automatic DNS API integration is not supported or when a user prefers handling DNS records personally. It requires action from the user to update DNS records at specified stages.

Explanation:

• --issue: Begins the procedure for acquiring the certificate.
• --dns: Entry to use DNS mode is specified but done manually here.
• --domain example.com: Lists the domain needing certification.
• --yes-I-know-dns-manual-mode-enough-go-ahead-please: Confirms user acknowledgment of the manual process, mitigating risk of human error in DNS updates.

Example Output:

[Fri Oct 8 13:00:00 UTC 2021] Manual DNS mode initiated
[Fri Oct 8 13:00:05 UTC 2021] Please add the following DNS TXT record
[Fri Oct 8 13:00:05 UTC 2021] Domain: _acme-challenge.example.com
[Fri Oct 8 13:00:05 UTC 2021] Challenge token: HBYEUqOWt1yaz
[Fri Oct 8 13:00:05 UTC 2021] Press enter after you have added the record.
[User waits for DNS record confirmation]
[Fri Oct 8 13:15:20 UTC 2021] Verification successful
[Fri Oct 8 13:15:25 UTC 2021] Certificate for example.com installed successfully

Conclusion:

acme.sh is a versatile tool for obtaining SSL certificates using various DNS methods. Whether you prefer the convenience of automation or need flexibility in handling different DNS scenarios, these examples illustrate how acme.sh --dns can adapt to meet your SSL provisioning needs. From automating updates via well-known DNS APIs to handling validation via aliases or manually, each supported mode comes with distinct benefits suitable for specific environments and requirements.