How to use the command 'acme.sh' (with examples)

Acme.sh is a shell script that implements the ACME client protocol, serving as an alternative to the popular Certbot. It is used for obtaining SSL/TLS certificates, which are essential for securing websites through HTTPS. Acme.sh focuses on providing a lightweight, easily integrated solution that caters to various web server configurations and DNS providers, offering robust functionality like automatic certificate renewal, flexible installation options, and support for wildcard certificates.

Use case 1: Issue a certificate using webroot mode

Code:

acme.sh --issue --domain example.com --webroot /path/to/webroot

Motivation: Using webroot mode is ideal for users who have access to their web server’s file system and can specify a directory where acme.sh will place a temporary file for domain validation. This method is seamless for web hosting environments that allow file uploads.

Explanation:

• --issue: This argument tells acme.sh to start the process of obtaining a certificate.
• --domain example.com: The --domain flag specifies the domain for which the certificate is being issued.
• --webroot /path/to/webroot: The --webroot option specifies the absolute path to the directory where the temporary file should be placed for HTTP validation.

Example output:

[Mon Oct  2 09:28:37 UTC 2023] Creating domain key
[Mon Oct  2 09:28:37 UTC 2023] The domain key is here: /home/user/.acme.sh/example.com/example.com.key
[Mon Oct  2 09:28:37 UTC 2023] Single domain='example.com'
[Mon Oct  2 09:28:37 UTC 2023] Getting domain auth token for each domain
[Mon Oct  2 09:28:37 UTC 2023] Getting webroot for domain='example.com'
...
[Mon Oct  2 09:28:50 UTC 2023] Your cert is in /home/user/.acme.sh/example.com/example.com.cer

Use case 2: Issue a certificate for multiple domains using standalone mode using port 80

Code:

acme.sh --issue --standalone --domain example.com --domain www.example.com

Motivation: Standalone mode is suitable for environments where a web server is not currently running or cannot be used for verification. This method starts its own temporary web server to complete domain validation on port 80.

Explanation:

• --issue: Initiates the certificate issuance process.
• --standalone: Specifies that acme.sh should use its built-in standalone mode for validation.
• --domain example.com: The primary domain to be included in the certificate.
• --domain www.example.com: An additional domain (subject alternative name) for which the certificate should be valid.

Example output:

[Mon Oct  2 09:35:10 UTC 2023] Single domain='example.com'
[Mon Oct  2 09:35:10 UTC 2023] Getting domain auth token for each domain
[Mon Oct  2 09:35:10 UTC 2023] Getting webroot for domain='example.com'
[Mon Oct  2 09:35:10 UTC 2023] Verifying:example.com
[Mon Oct  2 09:35:10 UTC 2023] Pending
[Mon Oct  2 09:35:10 UTC 2023] Success
...
[Mon Oct  2 09:35:25 UTC 2023] Your cert is in /home/user/.acme.sh/example.com/example.com.cer

Use case 3: Issue a certificate using standalone TLS mode using port 443

Code:

acme.sh --issue --alpn --domain example.com

Motivation: This mode is used when port 80 cannot be opened, but HTTPS communication over port 443 is feasible. ALPN (Application-Layer Protocol Negotiation) allows the use of HTTP/2 for validation.

Explanation:

• --issue: Starts the process of obtaining a certificate.
• --alpn: Enables standalone TLS mode with ALPN for domain validation.
• --domain example.com: Specifies the domain you wish to get a certificate for.

Example output:

[Mon Oct  2 09:42:10 UTC 2023] Standalone mode.
[Mon Oct  2 09:42:10 UTC 2023] Successfully sign API response payload
...
[Mon Oct  2 09:42:20 UTC 2023] Your cert is in /home/user/.acme.sh/example.com/example.com.cer

Use case 4: Issue a certificate using a working Nginx configuration

Code:

acme.sh --issue --nginx --domain example.com

Motivation: Using the Nginx mode allows the script to utilize the running Nginx web server for domain verification, modifying the Nginx configuration temporarily to comply with ACME protocol challenges.

Explanation:

• --issue: Triggers the process of certificate issuance.
• --nginx: Specifies that an existing Nginx configuration should be used for authenticating the domain.
• --domain example.com: The target domain to get the certificate for.

Example output:

[Mon Oct  2 09:50:07 UTC 2023] Using Nginx mode
[Mon Oct  2 09:50:07 UTC 2023] Single domain='example.com'
...
[Mon Oct  2 09:50:20 UTC 2023] Your cert is in /home/user/.acme.sh/example.com/example.com.cer

Use case 5: Issue a certificate using a working Apache configuration

Code:

acme.sh --issue --apache --domain example.com

Motivation: This mode is perfect for Apache users. Acme.sh will leverage the existing Apache configuration to automatically configure the server to pass domain validation challenges.

Explanation:

• --issue: Begins the certificate request process.
• --apache: Instructs acme.sh to manipulate the Apache configuration temporarily for validation.
• --domain example.com: Specifies the domain for which the certificate will be issued.

Example output:

[Mon Oct  2 09:55:45 UTC 2023] Using Apache mode
[Mon Oct  2 09:55:45 UTC 2023] Single domain='example.com'
...
[Mon Oct  2 09:55:58 UTC 2023] Your cert is in /home/user/.acme.sh/example.com/example.com.cer

Use case 6: Issue a wildcard (*) certificate using an automatic DNS API mode

Code:

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

Motivation: Wildcard certificates are best for securing subdomains. This mode involves DNS-based verification, where acme.sh automatically interfaces with the DNS provider’s API (like Cloudflare, in this case) to create the necessary DNS records.

Explanation:

• --issue: Initiates the process of issuing a wildcard certificate.
• --dns dns_cf: Specifies the use of Cloudflare’s DNS API for domain verification.
• --domain *.example.com: Requests a wildcard certificate that applies to any subdomains of example.com.

Example output:

[Mon Oct  2 10:00:30 UTC 2023] Single domain='*.example.com'
[Mon Oct  2 10:00:30 UTC 2023] Getting domain auth token for each domain
...
[Mon Oct  2 10:00:45 UTC 2023] Your cert is in /home/user/.acme.sh/example.com/example.com.cer

Use case 7: Install certificate files into the specified locations

Code:

acme.sh --install-cert -d example.com --key-file /path/to/example.com.key --fullchain-file /path/to/example.com.cer --reloadcmd "systemctl force-reload nginx"

Motivation: This command is critical for deploying the issued certificate into the appropriate locations on your server. It supports automated certificate renewals by providing paths and allowing you to specify a command to reload your web services.

Explanation:

• --install-cert: Instructs acme.sh to install the certificate.
• -d example.com: The domain for which the certificate is being installed.
• --key-file /path/to/example.com.key: Specifies the location where the private key will be saved.
• --fullchain-file /path/to/example.com.cer: Determines where the full chain certificate will be saved.
• --reloadcmd "systemctl force-reload nginx": A custom command to restart the Nginx server and import the new certificate.

Example output:

[Mon Oct  2 10:06:30 UTC 2023] Installing key to:/path/to/example.com.key
[Mon Oct  2 10:06:30 UTC 2023] Installing certificate to:/path/to/example.com.cer
...
[Mon Oct  2 10:06:45 UTC 2023] Run reload cmd: systemctl force-reload nginx
...

Conclusion:

Acme.sh is a powerful and flexible tool for obtaining and managing SSL/TLS certificates. Its command-line simplicity combined with the vast array of use case options allows it to be implemented across a wide variety of systems and configurations. Whether you’re dealing with a simple website or a complex infrastructure requiring wildcard certificates, acme.sh presents a solution designed to align with your specific needs without unnecessary complexity.