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.
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
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.
To upgrade acme.sh to the latest version, you can simply run the command below:
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: