acme.sh implements the acme protocol, allowing you to generate free certificates from Let’s Encrypt.

Main Steps:

1. Install acme.sh
2. Generate certificates
3. Copy certificates to Nginx/Apache or other services
4. Renew certificates
5. Update acme.sh
6. Troubleshooting in case of errors

Let’s dive into the details.

1. Install acme.sh

Installing is simple—just one command:

1

curl https://get.acme.sh | sh -s email=[email protected]

Both regular and root users can install and use it. The installation process includes the following steps:

1. The acme.sh script is installed to your home directory:

1

~/.acme.sh/

And it creates a shell alias in your .bashrc for easy usage: alias acme.sh=~/.acme.sh/acme.sh.

2. It automatically creates a cron job that checks all certificates daily at 00:00. If any certificates are nearing expiration, they will be automatically renewed.

For more advanced installation options, refer to: Acme.sh Installation Guide.

Note: The installation process does not interfere with existing system functionalities or files; all modifications are confined to the installation directory: ~/.acme.sh/.

2. Generate Certificates

acme.sh supports all the validation protocols of the acme protocol, typically through two methods: HTTP and DNS validation.

1. HTTP Method

To verify your domain ownership, you need to place a file in your website’s root directory, after which you can generate your certificate:

1

acme.sh --issue -d mydomain.com -d www.mydomain.com --webroot /home/wwwroot/mydomain.com/

Just specify your domain and the root directory where your website files reside. acme.sh will automatically generate the validation file, place it in the website’s root directory, and complete the verification. Afterward, it smartly deletes the validation file, ensuring there are no side effects.

If you’re using an Apache server, acme.sh can automatically complete verification through the Apache configuration without needing to specify the web root:

1

acme.sh --issue -d mydomain.com --apache

If you are using an Nginx server or a reverse proxy, acme.sh also intelligently completes the verification through the Nginx configuration without requiring the web root:

1

acme.sh --issue -d mydomain.com --nginx

Note: In both Apache and Nginx modes, acme.sh restores the config state after completing verification, so your configurations remain unchanged. The benefit is that you don’t have to worry about accidental misconfigurations, but keep in mind that you will need to configure the SSL settings manually. Otherwise, while the certificate will be generated successfully, your website will not be accessible via HTTPS. For security reasons, it’s advisable to manually configure your settings.

If you haven’t started any web services and port 80 is open, acme.sh can also temporarily act as a web server and listen on port 80 to complete verification:

1

acme.sh --issue -d mydomain.com --standalone

For more advanced usage, refer to: How to Issue a Certificate.

2. Manual DNS Method

For manual verification, you add a TXT record to your domain’s DNS settings to confirm domain ownership.

The advantage of this method is that you don’t need any web server or public IP address; you only require the DNS records to complete verification. The downside is that unless you configure Automatic DNS API, using this method means acme.sh won’t be able to automatically renew your certificates; you’ll have to repeat the verification manually each time.

1

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

Next, acme.sh will provide the necessary DNS records. You just need to add the TXT record to your domain management panel.

After the DNS changes propagate, you can renew the certificate:

1

acme.sh --renew -d mydomain.com --yes-I-know-dns-manual-mode-enough-go-ahead-please

Note that the second command uses --renew.

The real power of the DNS method lies in using API integrations with domain registrars to automatically add TXT records for verification.

acme.sh currently supports automatic integrations with various DNS providers, including Cloudflare, DNSPod, CloudXNS, GoDaddy, and OVH, among many others.

For example, to use DNSPod, first log into your DNSPod account to generate your API ID and API key (both are free). Then:

1
2
3

export DP_Id="1234"
export DP_Key="sADDsdasdgdsf"
acme.sh --issue --dns dns_dp -d aa.com -d www.aa.com

The certificate will be generated automatically. The provided API ID and key will be saved for future use, so you won’t need to specify them again when using the DNSPod API:

1

acme.sh --issue -d mydomain2.com --dns dns_dp

For detailed API usage, visit: DNS API README.

3. Copy/Install Certificates

After generating your certificate, the next step is to copy it to the location where it will be used.

Note that the default generated certificates are stored in the installation directory: ~/.acme.sh/. Please do not directly use the files in this directory in your Nginx/Apache configuration, as these files are intended for internal use, and the directory structure may change.

The correct approach is to use the --install-cert command and specify the target paths, which will copy the certificate files to the appropriate locations. For example:

Apache example:

1
2
3
4
5

acme.sh --install-cert -d example.com \
--cert-file /path/to/certfile/in/apache/cert.pem \
--key-file /path/to/keyfile/in/apache/key.pem \
--fullchain-file /path/to/fullchain/certfile/apache/fullchain.pem \
--reloadcmd "service apache2 force-reload"

Nginx example:

1
2
3
4

acme.sh --install-cert -d example.com \
--key-file /path/to/keyfile/in/nginx/key.pem \
--fullchain-file /path/to/fullchain/nginx/cert.pem \
--reloadcmd "service nginx force-reload"

(A friendly reminder: use service nginx force-reload instead of service nginx reload. Testing shows that reload may not reload the certificates, so it’s safer to use force-reload.)

In Nginx, the configuration for ssl_certificate should point to /etc/nginx/ssl/fullchain.cer instead of /etc/nginx/ssl/<domain>.cer, otherwise, an SSL Labs test may report Chain issues Incomplete.

The --install-cert command can include many parameters to specify the target files and also allows you to set reload commands that will be run automatically after the certificates are updated.

For detailed parameters, refer to: Install the Issued Certificate.

It’s worth noting that all specified parameters will be recorded automatically and reused during future certificate renewals.

4. View Installed Certificate Information

To view the information about the installed certificate, use:

1

acme.sh --info -d example.com

This will output information like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

DOMAIN_CONF=/root/.acme.sh/example.com/example.com.conf
Le_Domain=example.com
Le_Alt=no
Le_Webroot=dns_ali
Le_PreHook=
Le_PostHook=
Le_RenewHook=
Le_API=https://acme-v02.api.letsencrypt.org/directory
Le_Keylength=
Le_OrderFinalize=https://acme-v02.api.letsencrypt.org/acme/finalize/23xxxx150/781xxxx4310
Le_LinkOrder=https://acme-v02.api.letsencrypt.org/acme/order/233xxx150/781xxxx4310
Le_LinkCert=https://acme-v02.api.letsencrypt.org/acme/cert/04cbd28xxxxxx349ecaea8d07
Le_CertCreateTime=1649358725
Le_CertCreateTimeStr=Thu Apr  7 19:12:05 UTC 2022
Le_NextRenewTimeStr=Mon Jun  6 19:12:05 UTC 2022
Le_NextRenewTime=1654456325
Le_RealCertPath=
Le_RealCACertPath=
Le_RealKeyPath=/etc/acme/example.com/privkey.pem
Le_ReloadCmd=service nginx force-reload
Le_RealFullChainPath=/etc/acme/example.com/chain.pem