Acme.sh is a script written purely in bash language. It is a simple and powerful tool used to automatically generate and issue ssl certificates. By default, acme.sh is used to ease the generation and renewal of Lets Encrypt SSL certificates but it also supports other free SSL certificates. It works on most operating systems and also works best with DNS challenge. You do not have to be root to use acme.sh but it is highly recommended.

Acme.sh Supported CA

Acme works with Let’s Encrypt by default but it still supoorts other CA as below:

• Letsencrypt.org CA(default)
• ZeroSSL.com CA
• BuyPass.com CA
• Pebble strict Mode

Acme.sh Supported Modes

The following are validation methods supported by acme.sh that can be used in confirming domain ownership.

• Webroot mode
• Standalone mode
• Standalone tls-alpn mode
• Apache mode
• Nginx mode
• DNS mode
• DNS alias mode
• Stateless mode

How to Install Acme.sh on Linux

You can easily install acme.sh by using any of the below methods:

# curl
curl https://get.acme.sh | sh

# wget
wget -O -  https://get.acme.sh | sh

# Git
git clone https://github.com/acmesh-official/acme.sh.git
cd ./acme.sh
./acme.sh --install

The above installer will perform the following actions:

• Create and copy acme.sh to your home dir ($HOME): ~/.acme.sh/. All certs will be placed in this folder too.
• Create alias for: acme.sh=~/.acme.sh/acme.sh.
• Create daily cron job to check and renew the certs if needed.

Issuing Let’s Encrypt SSL Certificate with Acme.sh

Once acme.sh installed you can simply issue certificate with the below different options.

Webroot Mode

If you have a webserver already running, you should use webroot mode and you must have write access to the web root folder. The generated certificates will be placed in ~/.acme.sh/example.com/ and will be renewed automatically after every 60 days.

For a single domain:

acme.sh --issue -d example.com -w /var/www/example.com

For many domains in the same cert and webroot mode, you must point all the domains to the same webroot folder.

acme.sh --issue -d example.com -d www.example.com -d cp.example.com -w /var/www/example.com

Issue ECC Certs

Let’s encrypt can now issue ECDSA certs and acme.sh supports them as well. All you need to do it to add keylength parameter.

For Single domain ECC/ECDSA cert and Webroot mode:

acme.sh --issue -w /home/wwwroot/example.com -d example.com --keylength ec-256

For multiple domains in the same ECC/ECDSA cert and Webroot mode:

acme.sh --issue -d example.com -d www.example.com -d mail.example.com --webroot /var/www/example.com --keylength ec-256

Note the valid values for keylength:

• ec-256 (prime256v1, “ECDSA P-256”)
• ec-384 (secp384r1, “ECDSA P-384”)
• ec-521 (secp521r1, “ECDSA P-521”, which is not supported by Let’s Encrypt yet.)

Acme.sh and Apache Mode

As explained above, webserver requires you to use webroot mode. However, if you are particularly installing a cert for Apache, you can just use Apache mode instead. This mode will not write files to web root folder. The command will force use of Apache plugin automatically. You need to be root to be able to interact with Apache server.

For a single domain:

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

For multiple domains:

acme.sh --issue --apache -d example.com -d www.example.com -d cp.example.com

Acme.sh and Nginx Mode

Just like Apache Mode, Nginx mode will not write files to web root folder. The command below will force use of Nginx plugin automatically. You need to be root to be able to interact with Nginx server.

For single domain:

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

For multiple domains:

acme.sh --issue --nginx -d example.com -d www.example.com -d cp.example.com

Sometimes Nginx configuration file cannot be found be found automatically and you may need to specify in your command as below:

acme.sh  --issue  -d example.com  --nginx /etc/nginx/nginx.conf

Or specify the website conf:

acme.sh  --issue  -d example.com  --nginx /etc/nginx/conf.d/example.com.conf

Note that with Apache and Nginx modes, the cert will be issued but will not change web server configurations files. You need to manually edit Nginx and Apache configuration files to use the issued cert.

Acme and Standalone Mode

If you are not using a web server but still has port 80 free, you can use standalone mode to issue ssl certificate. You should have root privileges to run the commands.

For single domain:

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

For many domains in the same cert:

acme.sh --issue -d example.com -d www.example.com -d mail.example.com --standalone

Acme.sh and Standalone TLS ALPN Mode

Here, you do not have a web server but port 443 is free. Acme.sh comes with an inbuilt standalone TLS web server that can listen on port 443 to issue cert. You should have root privileges to run the commands

Single domain:

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

Multiple domains in the same cert:

acme.sh --issue -d example.com -d www.example.com –alpn

Automatic DNS API Integration

For DNS providers that have an API, acme can use it to automatically add the TXT record instead of you doing it manually. In this case, the certificate will be automatically renewed and issued. You will need to configure API key and email and request for the certificate as below, example with Cloudflare:

export CF_Key="sdfsdfsdfljlbjkljlkjsdfoiwje" 
export CF_Email="[email protected]"
acme.sh --issue -d example.com --dns dns_cf

If you are requiesting for a wildcard ssl and using Cloudfare DNS Api mode, run the commands below:

export CF_Key="sdfsdfsdfljlbjkljlkjsdfoiwje" 
export CF_Email="[email protected]" 
acme.sh --issue -d example.com -d '*.example.com' --dns dns_cf

However, if your DNS does not support API, you will be required to add the TXT record manually. One you request for a certificate, you will get a TXT record to manually add to your DNS, as below:

$ acme.sh --issue --dns -d example.com -d www.example.com -d cp.example.com
Add the following txt record: 
Domain:_acme-challenge.example.com 
Txt value:9ihDbjYfTExAYeDs4DBUeuTo18KBzwvTEjUnSwd32-c 

Add the following txt record: 
Domain:_acme-challenge.www.example.com 
Txt value:9ihDbjxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

Please add those txt records to the domains. Waiting for the dns to take effect.

And then rerun with ‘renew’ as below:

acme.sh --renew -d example.com

This manual method will not automatically renew your certificate and you will have to add another TXT record when it is time to renew.

Installing Let’s Encrypt SSL Cert with Acme.sh

Once you have the certificate generated, you may need to install or copy it to a certain location on your system. You could be running a web server like Nginx or Apache or you could be having your own way of storing the certs.

You should not use the certificates in ~/.acme.sh/ folder since they are for internal use and the folder structure may change later. Create the directories you would want to store the certs and only use the below commands to install/ copy.

To install Let’s Encrypt for Nginx, use the example below:

acme.sh --install-cert \ 
       --domain example.com \ 
       --cert-file /path/to/cert/cert.pem \ 
       --key-file /path/to/keyfile/key.pem \ 
       --fullchain-file /path/to/fullchain/fullchain.pem \ 
       --reloadcmd "sudo systemctl reload nginx.service"

To install Let’s Encrypt for Apache web server, check the example below:

acme.sh --install-cert \ 
       --domain example.com \  
       --cert-file /path/to/cert/cert.pem \ 
       --key-file /path/to/keyfile/key.pem \ 
       --fullchain-file /path/to/fullchain/fullchain.pem \ 
       --reloadcmd "sudo systemctl reload apache2.service"

You need to ensure that the above parameters are properly entered since they will be stored in Acme.sh configuration file and will be called during renewel. The ‘reloadcmd’ necessary to ensure that the web server picks the new changes.

Renewing Let’s Encrypt with Acme.sh

As explained earlier, acme.sh will automatically renew the certs after 60 days and you do nit have to do a manual renew. However, in a case where you would want to force let’s encrypt renewal, you can run the command below:

acme.sh --renew -d example.com --force

For ecc cert:

acme.sh --renew -d example.com --force –ecc

How to get Pkcs12(pfx) Format with Acme.sh

Once the cert has been issued , you can convert it to pkcs12(pfx) using to Pkcs command as below:

acme.sh  --toPkcs  -d <domain>  [--password pfx-password] 

How to Run Acme.sh with Cygwin on Windows

To run acme.sh on Linux, we are going to install Cygwin that will enable us to install acme.sh. Cygwin is a large collection of GNU and Open Source tools which provide functionality similar to a Linux distribution on Windows. Follow the steps below:

• Download cygwin installer: setup-x86.exe or setup-x86_64.exe from Cygwin official website
• In the installer, select: Net: curl and Net: socat to install.
• Once installed, open the Cygwin window and use curl to install acme.sh online as explained at the beginning of the tutorial.
• A scheduler task will be installed in your Windows scheduler to renew your certs.

Upgrade Acme.sh

To upgrade acme.sh to the latest version, you can simply run the command below:

acme.sh --upgrade

Or enable automatic upgrade with the below command:

acme.sh --upgrade --auto-upgrade

This has been a guide on how to automate the generation and renewal of Let’s Encrypt ssl certificates with Acme.sh. I hope the guide has been useful. Check more interesting guides below:

• How To Secure Jira With Let’s Encrypt SSL Certificate
• How To Run VS Code in browser secured with Let’s Encrypt
• Top Books For Learning Apache and Nginx Web Servers