Welcome to LeviFREE's Blog

What is acme.sh?#

acme.sh is an ACME protocol client written purely in Shell. Compared to the official Certbot, it has the following significant advantages:

• Lightweight: No dependencies, no need to install Python.
• Compatibility: Supports almost all Linux distributions.
• Feature-rich: Automatically handles cron tasks, supports auto-injection of certificates into Nginx/Apache, and supports Docker deployment.
• DNS Support: Built-in API support for 100+ DNS providers.

Step 1: Install acme.sh#

The installation process is very simple, requiring only one command. It is recommended to switch to the root user to execute.

1
# Replace with your real email, used for receiving certificate expiration reminders
2
curl https://get.acme.sh | sh -s email=my@example.com

After installation is complete, the script will automatically perform the following operations:

1. Install acme.sh to the ~/.acme.sh/ directory.
2. Create an alias acme.sh=~/.acme.sh/acme.sh alias.
3. Automatically create a daily Cron Job to check if certificates need updating.

1
source ~/.bashrc

Step 2: Switch Default CA (Recommended)#

acme.sh uses ZeroSSL as the default Certificate Authority. If you are more accustomed to using Let’s Encrypt, you can switch at any time:

1
acme.sh --set-default-ca --server letsencrypt

Step 3: Apply for Certificate (DNS Method Recommended)#

acme.sh supports both HTTP verification and DNS verification. DNS verification is strongly recommended because:

1. It supports Wildcard certificates (like *.example.com).
2. It does not rely on a Web server and does not require a public IP (can be used on intranet servers).
3. If you don’t use API auto-verification, manually resolving TXT records every 3 months is extremely cumbersome.

1
export CF_Token="Your_API_Token"
2
export CF_Account_ID="Your_Account_ID"
3

4
# Apply for a wildcard certificate (including main domain and all subdomains)
5
# --keylength ec-256 means applying for a more modern, faster ECC certificate
6
acme.sh --issue --dns dns_cf -d example.com -d *.example.com --keylength ec-256

Step 4: Install Certificate to Web Server#

Do not ever directly point your Nginx/Apache configuration files to the files within the ~/.acme.sh/ directory. The structure of that directory could change at any time.

You should use the --install-cert command to copy the certificates to a specified location, and instruct the script to reload the Web service.

1
mkdir -p /etc/nginx/ssl
2

3
acme.sh --install-cert -d example.com --ecc \
4
--key-file       /etc/nginx/ssl/server.key  \
5
--fullchain-file /etc/nginx/ssl/fullchain.cer \
6
--reloadcmd     "systemctl force-reload nginx"

1
server {
2
    listen 443 ssl http2;
3
    server_name example.com;
4

5
    # Certificate path configuration
6
    ssl_certificate     /etc/nginx/ssl/fullchain.cer;
7
    ssl_certificate_key /etc/nginx/ssl/server.key;
8

9
    # Recommended SSL security parameters
10
    ssl_protocols TLSv1.2 TLSv1.3;
11
    ssl_ciphers EECDH+CHACHA20:EECDH+CHACHA20-draft:EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:!MD5;
12

13
    # ... Other configurations
14
}

Advanced: How to Update Certificates?#

1
acme.sh --upgrade --auto-upgrade

Common Troubleshooting#

1. Unknown error (DNS verification failed)

   • Check if the API Token permissions are correct (must include Edit permission for Zone.DNS).
   • Check if the DNS server is effective. Sometimes propagation is delayed; you can add --dnssleep 60 parameter to let the script wait a little longer.

2. Web verification failed

   • Ensure port 80 is open and not blocked by a firewall.
   • If you are just temporarily verifying and don’t have Nginx, you can use the --standalone mode (requires temporarily stopping services occupying port 80).

Disclaimer#