An ACME Shell script: acme.sh

• An ACME protocol client written purely in Shell (Unix shell) language.
• Full ACME protocol implementation.
• Support ECDSA certs
• Support SAN and wildcard certs
• Simple, powerful and very easy to use. You only need 3 minutes to learn it.
• Bash, dash and sh compatible.
• Purely written in Shell with no dependencies on python.
• Just one script to issue, renew and install your certificates automatically.
• DOES NOT require root/sudoer access.
• Docker ready
• IPv6 ready
• Cron job notifications for renewal or error etc.
• A fork which doesn't target your Apache / Nginx configuration with intention to mess them completely up

It's probably the easiest & smartest shell script to automatically issue & renew the free certificates.

Wiki: https://github.com/acmesh-official/acme.sh/wiki

For Docker Fans: acme.sh 💕 Docker

Twitter: @neilpangxa

中文说明

Who:

• FreeBSD.org
• ruby-china.org
• Proxmox
• pfsense
• webfaction
• Loadbalancer.org
• discourse.org
• Centminmod
• splynx
• archlinux
• opnsense.org
• CentOS Web Panel
• lnmp.org
• more...

Tested OS

Check our testing project:

https://github.com/acmesh-official/acmetest

Supported CA

• ZeroSSL.com CA(default)
• Letsencrypt.org CA
• BuyPass.com CA
• SSL.com CA
• Google.com Public CA
• Pebble strict Mode
• Any other RFC8555-compliant CA

Supported modes

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

1. How to install

1. Install online

curl https://raw.githubusercontent.com/HQJaTu/acme.sh/main/acme.sh | sh -s email=my@example.com

Or:

wget -O -  https://raw.githubusercontent.com/HQJaTu/acme.sh/main/acme.sh | sh -s email=my@example.com

2. Or, Install from git

Clone this project and launch installation:

git clone https://github.com/HQJaTu/acme.sh.git
cd ./acme.sh
./acme.sh --install -m my@example.com

You don't have to be root then, although it is recommended.

Advanced Installation: https://github.com/acmesh-official/acme.sh/wiki/How-to-install

The installer will perform 3 actions:

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

Cron entry example:

0 0 * * * "/home/user/.acme.sh"/acme.sh --cron --home "/home/user/.acme.sh" > /dev/null

After the installation, you must close the current terminal and reopen it to make the alias take effect.

Ok, you are ready to issue certs now.

Show help message:

root@v1:~# acme.sh -h

2. Just issue a cert

Example 1: Single domain.

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

or:

acme.sh --issue -d example.com -w /home/username/public_html

or:

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

Example 2: Multiple domains in the same cert.

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

The parameter /home/wwwroot/example.com or /home/username/public_html or /var/www/html is the web root folder where you host your website files. You MUST have write access to this folder.

Second argument "example.com" is the main domain you want to issue the cert for. You must have at least one domain there.

You must point and bind all the domains to the same webroot dir: /home/wwwroot/example.com.

The certs will be placed in ~/.acme.sh/example.com/

The certs will be renewed automatically every 60 days.

More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert

3. Install the cert to Apache/Nginx etc.

Not with this tool!

If you want a poorly written crappy tool to overwrite your precious configuration, use something else!

4. Use Standalone server to issue cert

(requires you to be root/sudoer or have permission to listen on port 80 (TCP))

Port 80 (TCP) MUST be free to listen on, otherwise you will be prompted to free it and try again.

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

More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert

5. Use Standalone ssl server to issue cert

(requires you to be root/sudoer or have permission to listen on port 443 (TCP))

Port 443 (TCP) MUST be free to listen on, otherwise you will be prompted to free it and try again.

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

More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert

8. Automatic DNS API integration

If your DNS provider supports API access, we can use that API to automatically issue the certs.

You don't have to do anything manually!

Currently acme.sh supports most of the dns providers:

https://github.com/acmesh-official/acme.sh/wiki/dnsapi

1. CloudFlare.com API
2. DNSPod.cn API
3. CloudXNS.com API
4. GoDaddy.com API
5. PowerDNS.com API
6. OVH, kimsufi, soyoustart and runabove API
7. nsupdate API
8. LuaDNS.com API
9. DNSMadeEasy.com API
10. AWS Route 53
11. aliyun.com(阿里云) API
12. ISPConfig 3.1 API
13. Alwaysdata.com API
14. Linode.com API
15. FreeDNS (https://freedns.afraid.org/)
16. cyon.ch
17. Domain-Offensive/Resellerinterface/Domainrobot API
18. Gandi LiveDNS API
19. Knot DNS API
20. DigitalOcean API (native)
21. ClouDNS.net API
22. Infoblox NIOS API (https://www.infoblox.com/)
23. VSCALE (https://vscale.io/)
24. Dynu API (https://www.dynu.com)
25. DNSimple API
26. NS1.com API
27. DuckDNS.org API
28. Name.com API
29. Dyn Managed DNS API
30. Yandex PDD API (https://pdd.yandex.ru)
31. Hurricane Electric DNS service (https://dns.he.net)
32. UnoEuro API (https://www.unoeuro.com/)
33. INWX (https://www.inwx.de/)
34. Servercow (https://servercow.de)
35. Namesilo (https://www.namesilo.com)
36. InternetX autoDNS API (https://internetx.com)
37. Azure DNS
38. selectel.com(selectel.ru) DNS API
39. zonomi.com DNS API
40. DreamHost.com API
41. DirectAdmin API
42. KingHost (https://www.kinghost.com.br/)
43. Zilore (https://zilore.com)
44. Loopia.se API
45. acme-dns (https://github.com/joohoi/acme-dns)
46. TELE3 (https://www.tele3.cz)
47. EUSERV.EU (https://www.euserv.eu)
48. DNSPod.com API (https://www.dnspod.com)
49. Google Cloud DNS API
50. ConoHa (https://www.conoha.jp)
51. netcup DNS API (https://www.netcup.de)
52. GratisDNS.dk (https://gratisdns.dk)
53. Namecheap API (https://www.namecheap.com/)
54. MyDNS.JP API (https://www.mydns.jp/)
55. hosting.de (https://www.hosting.de)
56. Neodigit.net API (https://www.neodigit.net)
57. Exoscale.com API (https://www.exoscale.com/)
58. PointDNS API (https://pointhq.com/)
59. Active24.cz API (https://www.active24.cz/)
60. do.de API (https://www.do.de/)
61. NederHost API (https://www.nederhost.nl/)
62. Nexcess API (https://www.nexcess.net)
63. Thermo.io API (https://www.thermo.io)
64. Futurehosting API (https://www.futurehosting.com)
65. Rackspace Cloud DNS (https://www.rackspace.com)
66. Online.net API (https://online.net/)
67. MyDevil.net (https://www.mydevil.net/)

And:

lexicon DNS API: https://github.com/Neilpang/acme.sh/wiki/How-to-use-lexicon-dns-api (DigitalOcean, DNSimple, DNSMadeEasy, DNSPark, EasyDNS, Namesilo, NS1, PointHQ, Rage4 and Vultr etc.)

More APIs coming soon...

If your DNS provider is not on the supported list above, you can write your own DNS API script easily. If you do, please consider submitting a Pull Request and contribute it to the project.

For more details: How to use DNS API

9. Use DNS manual mode:

See: https://github.com/acmesh-official/acme.sh/wiki/dns-manual-mode first.

If your dns provider doesn't support any api access, you can add the txt record by hand.

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

You should get an output like below:

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.

Then just rerun with renew argument:

acme.sh --renew -d example.com

Ok, it's done.

Take care, this is dns manual mode, it can not be renewed automatically. you will have to add a new txt record to your domain by your hand when you renew your cert.

Please use dns api mode instead.

10. Issue ECC certificates

Let's Encrypt can now issue ECDSA certificates.

And we support them too!

Just set the keylength parameter with a prefix ec-.

For example:

Single domain ECC certificate

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

SAN multi domain ECC certificate

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

Please look at the keylength parameter above.

Valid values are:

1. ec-256 (prime256v1, "ECDSA P-256")
2. ec-384 (secp384r1, "ECDSA P-384")
3. ec-521 (secp521r1, "ECDSA P-521", which is not supported by Let's Encrypt yet.)

11. Issue Wildcard certificates

It's simple, just give a wildcard domain as the -d parameter.

acme.sh  --issue -d example.com  -d '*.example.com'  --dns dns_cf

12. How to renew the certs

No, you don't need to renew the certs manually. All the certs will be renewed automatically every 60 days.

However, you can also force to renew a cert:

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

or, for ECC cert:

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

13. How to stop cert renewal

To stop renewal of a cert, you can execute the following to remove the cert from the renewal list:

acme.sh --remove -d example.com [--ecc]

The cert/key file is not removed from the disk.

You can remove the respective directory (e.g. ~/.acme.sh/example.com) by yourself.

14. How to upgrade acme.sh

acme.sh is in constant development, so it's strongly recommended to use the latest code.

You can update acme.sh to the latest code:

acme.sh --upgrade

15. Issue a cert from an existing CSR

https://github.com/acmesh-official/acme.sh/wiki/Issue-a-cert-from-existing-CSR

16. Send notifications in cronjob

https://github.com/acmesh-official/acme.sh/wiki/notify

16. Send notifications in cronjob

https://github.com/Neilpang/acme.sh/wiki/notify

17. Under the Hood

Speak ACME language using shell, directly to "Let's Encrypt".

TODO:

18. Acknowledgments

1. Acme-tiny: https://github.com/diafygi/acme-tiny
2. ACME protocol: https://github.com/ietf-wg-acme/acme

19. License & Others

License is GPLv3

Please Star and Fork me.