]> git.proxmox.com Git - mirror_acme.sh.git/blob - README.md
fix format
[mirror_acme.sh.git] / README.md
1 # An ACME Shell script: acme.sh
2
3 ![LetsEncrypt](https://github.com/acmesh-official/acme.sh/workflows/LetsEncrypt/badge.svg)
4 ![Shellcheck](https://github.com/acmesh-official/acme.sh/workflows/Shellcheck/badge.svg)
5 ![PebbleStrict](https://github.com/acmesh-official/acme.sh/workflows/PebbleStrict/badge.svg)
6 ![DockerHub](https://github.com/acmesh-official/acme.sh/workflows/Build%20DockerHub/badge.svg)
7
8
9 <a href="https://opencollective.com/acmesh" alt="Financial Contributors on Open Collective"><img src="https://opencollective.com/acmesh/all/badge.svg?label=financial+contributors" /></a>
10 [![Join the chat at https://gitter.im/acme-sh/Lobby](https://badges.gitter.im/acme-sh/Lobby.svg)](https://gitter.im/acme-sh/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
11 [![Docker stars](https://img.shields.io/docker/stars/neilpang/acme.sh.svg)](https://hub.docker.com/r/neilpang/acme.sh "Click to view the image on Docker Hub")
12 [![Docker pulls](https://img.shields.io/docker/pulls/neilpang/acme.sh.svg)](https://hub.docker.com/r/neilpang/acme.sh "Click to view the image on Docker Hub")
13
14
15
16 - An ACME protocol client written purely in Shell (Unix shell) language.
17 - Full ACME protocol implementation.
18 - Support ACME v1 and ACME v2
19 - Support ACME v2 wildcard certs
20 - Simple, powerful and very easy to use. You only need 3 minutes to learn it.
21 - Bash, dash and sh compatible.
22 - Purely written in Shell with no dependencies on python or the official Let's Encrypt client.
23 - Just one script to issue, renew and install your certificates automatically.
24 - DOES NOT require `root/sudoer` access.
25 - Docker friendly
26 - IPv6 support
27 - Cron job notifications for renewal or error etc.
28
29 It's probably the `easiest & smartest` shell script to automatically issue & renew the free certificates from Let's Encrypt.
30
31 Wiki: https://github.com/acmesh-official/acme.sh/wiki
32
33 For Docker Fans: [acme.sh :two_hearts: Docker ](https://github.com/acmesh-official/acme.sh/wiki/Run-acme.sh-in-docker)
34
35 Twitter: [@neilpangxa](https://twitter.com/neilpangxa)
36
37
38 # [中文说明](https://github.com/acmesh-official/acme.sh/wiki/%E8%AF%B4%E6%98%8E)
39
40 # Who:
41 - [FreeBSD.org](https://blog.crashed.org/letsencrypt-in-freebsd-org/)
42 - [ruby-china.org](https://ruby-china.org/topics/31983)
43 - [Proxmox](https://pve.proxmox.com/wiki/Certificate_Management)
44 - [pfsense](https://github.com/pfsense/FreeBSD-ports/pull/89)
45 - [webfaction](https://community.webfaction.com/questions/19988/using-letsencrypt)
46 - [Loadbalancer.org](https://www.loadbalancer.org/blog/loadbalancer-org-with-lets-encrypt-quick-and-dirty)
47 - [discourse.org](https://meta.discourse.org/t/setting-up-lets-encrypt/40709)
48 - [Centminmod](https://centminmod.com/letsencrypt-acmetool-https.html)
49 - [splynx](https://forum.splynx.com/t/free-ssl-cert-for-splynx-lets-encrypt/297)
50 - [archlinux](https://www.archlinux.org/packages/community/any/acme.sh)
51 - [opnsense.org](https://github.com/opnsense/plugins/tree/master/security/acme-client/src/opnsense/scripts/OPNsense/AcmeClient)
52 - [CentOS Web Panel](http://centos-webpanel.com/)
53 - [lnmp.org](https://lnmp.org/)
54 - [more...](https://github.com/acmesh-official/acme.sh/wiki/Blogs-and-tutorials)
55
56 # Tested OS
57
58 | NO | Status| Platform|
59 |----|-------|---------|
60 |1|[![MacOS](https://github.com/acmesh-official/acme.sh/workflows/LetsEncrypt/badge.svg)](https://github.com/acmesh-official/acme.sh/actions?query=workflow%3ALetsEncrypt)|Mac OSX
61 |2|[![Windows](https://github.com/acmesh-official/acme.sh/workflows/LetsEncrypt/badge.svg)](https://github.com/acmesh-official/acme.sh/actions?query=workflow%3ALetsEncrypt)|Windows (cygwin with curl, openssl and crontab included)
62 |3|[![FreeBSD](https://github.com/acmesh-official/acme.sh/workflows/LetsEncrypt/badge.svg)](https://github.com/acmesh-official/acme.sh/actions?query=workflow%3ALetsEncrypt)|FreeBSD
63 |4|[![Solaris](https://github.com/acmesh-official/acme.sh/workflows/LetsEncrypt/badge.svg)](https://github.com/acmesh-official/acme.sh/actions?query=workflow%3ALetsEncrypt)|Solaris
64 |5|[![Ubuntu](https://github.com/acmesh-official/acme.sh/workflows/LetsEncrypt/badge.svg)](https://github.com/acmesh-official/acme.sh/actions?query=workflow%3ALetsEncrypt)| Ubuntu
65 |6|[![](https://acmesh-official.github.io/acmetest/status/pfsense.svg)](https://github.com/acmesh-official/acmetest#here-are-the-latest-status)|pfsense
66 |7|[![](https://acmesh-official.github.io/acmetest/status/openbsd.svg)](https://github.com/acmesh-official/acmetest#here-are-the-latest-status)|OpenBSD
67 |8|[![](https://acmesh-official.github.io/acmetest/status/debian-latest.svg)](https://github.com/acmesh-official/acmetest#here-are-the-latest-status)| Debian
68 |9|[![](https://acmesh-official.github.io/acmetest/status/centos-latest.svg)](https://github.com/acmesh-official/acmetest#here-are-the-latest-status)|CentOS
69 |10|[![](https://acmesh-official.github.io/acmetest/status/opensuse-leap-latest.svg)](https://github.com/acmesh-official/acmetest#here-are-the-latest-status)|openSUSE
70 |11|[![](https://acmesh-official.github.io/acmetest/status/alpine-latest.svg)](https://github.com/acmesh-official/acmetest#here-are-the-latest-status)|Alpine Linux (with curl)
71 |12|[![](https://acmesh-official.github.io/acmetest/status/archlinux-latest.svg)](https://github.com/acmesh-official/acmetest#here-are-the-latest-status)|Archlinux
72 |13|[![](https://acmesh-official.github.io/acmetest/status/fedora-latest.svg)](https://github.com/acmesh-official/acmetest#here-are-the-latest-status)|fedora
73 |14|[![](https://acmesh-official.github.io/acmetest/status/kalilinux-kali.svg)](https://github.com/acmesh-official/acmetest#here-are-the-latest-status)|Kali Linux
74 |15|[![](https://acmesh-official.github.io/acmetest/status/oraclelinux-latest.svg)](https://github.com/acmesh-official/acmetest#here-are-the-latest-status)|Oracle Linux
75 |16|[![](https://acmesh-official.github.io/acmetest/status/proxmox.svg)](https://github.com/acmesh-official/letest#here-are-the-latest-status)| Proxmox: See Proxmox VE Wiki. Version [4.x, 5.0, 5.1](https://pve.proxmox.com/wiki/HTTPS_Certificate_Configuration_(Version_4.x,_5.0_and_5.1)#Let.27s_Encrypt_using_acme.sh), version [5.2 and up](https://pve.proxmox.com/wiki/Certificate_Management)
76 |17|-----| Cloud Linux https://github.com/acmesh-official/acme.sh/issues/111
77 |18|[![](https://acmesh-official.github.io/acmetest/status/mageia.svg)](https://github.com/acmesh-official/acmetest#here-are-the-latest-status)|Mageia
78 |19|-----| OpenWRT: Tested and working. See [wiki page](https://github.com/acmesh-official/acme.sh/wiki/How-to-run-on-OpenWRT)
79 |20|[![](https://acmesh-official.github.io/acmetest/status/gentoo-stage3-amd64.svg)](https://github.com/acmesh-official/acmetest#here-are-the-latest-status)|Gentoo Linux
80 |21|[![](https://acmesh-official.github.io/acmetest/status/clearlinux-latest.svg)](https://github.com/acmesh-official/acmetest#here-are-the-latest-status)|ClearLinux
81
82 For all build statuses, check our [weekly build project](https://github.com/acmesh-official/acmetest):
83
84 https://github.com/acmesh-official/acmetest
85
86 # Supported CA
87
88 - Letsencrypt.org CA(default)
89 - [ZeroSSL.com CA](https://github.com/acmesh-official/acme.sh/wiki/ZeroSSL.com-CA)
90 - [BuyPass.com CA](https://github.com/acmesh-official/acme.sh/wiki/BuyPass.com-CA)
91 - [Pebble strict Mode](https://github.com/letsencrypt/pebble)
92 - Any other [RFC8555](https://tools.ietf.org/html/rfc8555)-compliant CA
93
94 # Supported modes
95
96 - Webroot mode
97 - Standalone mode
98 - Standalone tls-alpn mode
99 - Apache mode
100 - Nginx mode
101 - DNS mode
102 - [DNS alias mode](https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode)
103 - [Stateless mode](https://github.com/acmesh-official/acme.sh/wiki/Stateless-Mode)
104
105
106 # 1. How to install
107
108 ### 1. Install online
109
110 Check this project: https://github.com/acmesh-official/get.acme.sh
111
112 ```bash
113 curl https://get.acme.sh | sh -s email=my@example.com
114 ```
115
116 Or:
117
118 ```bash
119 wget -O - https://get.acme.sh | sh -s email=my@example.com
120 ```
121
122
123 ### 2. Or, Install from git
124
125 Clone this project and launch installation:
126
127 ```bash
128 git clone https://github.com/acmesh-official/acme.sh.git
129 cd ./acme.sh
130 ./acme.sh --install -m my@example.com
131 ```
132
133 You `don't have to be root` then, although `it is recommended`.
134
135 Advanced Installation: https://github.com/acmesh-official/acme.sh/wiki/How-to-install
136
137 The installer will perform 3 actions:
138
139 1. Create and copy `acme.sh` to your home dir (`$HOME`): `~/.acme.sh/`.
140 All certs will be placed in this folder too.
141 2. Create alias for: `acme.sh=~/.acme.sh/acme.sh`.
142 3. Create daily cron job to check and renew the certs if needed.
143
144 Cron entry example:
145
146 ```bash
147 0 0 * * * "/home/user/.acme.sh"/acme.sh --cron --home "/home/user/.acme.sh" > /dev/null
148 ```
149
150 After the installation, you must close the current terminal and reopen it to make the alias take effect.
151
152 Ok, you are ready to issue certs now.
153
154 Show help message:
155
156 ```sh
157 root@v1:~# acme.sh -h
158 ```
159
160 # 2. Just issue a cert
161
162 **Example 1:** Single domain.
163
164 ```bash
165 acme.sh --issue -d example.com -w /home/wwwroot/example.com
166 ```
167
168 or:
169
170 ```bash
171 acme.sh --issue -d example.com -w /home/username/public_html
172 ```
173
174 or:
175
176 ```bash
177 acme.sh --issue -d example.com -w /var/www/html
178 ```
179
180 **Example 2:** Multiple domains in the same cert.
181
182 ```bash
183 acme.sh --issue -d example.com -d www.example.com -d cp.example.com -w /home/wwwroot/example.com
184 ```
185
186 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.
187
188 Second argument **"example.com"** is the main domain you want to issue the cert for.
189 You must have at least one domain there.
190
191 You must point and bind all the domains to the same webroot dir: `/home/wwwroot/example.com`.
192
193 The certs will be placed in `~/.acme.sh/example.com/`
194
195 The certs will be renewed automatically every **60** days.
196
197 More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert
198
199
200 # 3. Install the cert to Apache/Nginx etc.
201
202 After the cert is generated, you probably want to install/copy the cert to your Apache/Nginx or other servers.
203 You **MUST** use this command to copy the certs to the target files, **DO NOT** use the certs files in **~/.acme.sh/** folder, they are for internal use only, the folder structure may change in the future.
204
205 **Apache** example:
206 ```bash
207 acme.sh --install-cert -d example.com \
208 --cert-file /path/to/certfile/in/apache/cert.pem \
209 --key-file /path/to/keyfile/in/apache/key.pem \
210 --fullchain-file /path/to/fullchain/certfile/apache/fullchain.pem \
211 --reloadcmd "service apache2 force-reload"
212 ```
213
214 **Nginx** example:
215 ```bash
216 acme.sh --install-cert -d example.com \
217 --key-file /path/to/keyfile/in/nginx/key.pem \
218 --fullchain-file /path/to/fullchain/nginx/cert.pem \
219 --reloadcmd "service nginx force-reload"
220 ```
221
222 Only the domain is required, all the other parameters are optional.
223
224 The ownership and permission info of existing files are preserved. You can pre-create the files to define the ownership and permission.
225
226 Install/copy the cert/key to the production Apache or Nginx path.
227
228 The cert will be renewed every **60** days by default (which is configurable). Once the cert is renewed, the Apache/Nginx service will be reloaded automatically by the command: `service apache2 force-reload` or `service nginx force-reload`.
229
230
231 **Please take care: The reloadcmd is very important. The cert can be automatically renewed, but, without a correct 'reloadcmd' the cert may not be flushed to your server(like nginx or apache), then your website will not be able to show renewed cert in 60 days.**
232
233 # 4. Use Standalone server to issue cert
234
235 **(requires you to be root/sudoer or have permission to listen on port 80 (TCP))**
236
237 Port `80` (TCP) **MUST** be free to listen on, otherwise you will be prompted to free it and try again.
238
239 ```bash
240 acme.sh --issue --standalone -d example.com -d www.example.com -d cp.example.com
241 ```
242
243 More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert
244
245 # 5. Use Standalone ssl server to issue cert
246
247 **(requires you to be root/sudoer or have permission to listen on port 443 (TCP))**
248
249 Port `443` (TCP) **MUST** be free to listen on, otherwise you will be prompted to free it and try again.
250
251 ```bash
252 acme.sh --issue --alpn -d example.com -d www.example.com -d cp.example.com
253 ```
254
255 More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert
256
257
258 # 6. Use Apache mode
259
260 **(requires you to be root/sudoer, since it is required to interact with Apache server)**
261
262 If you are running a web server, it is recommended to use the `Webroot mode`.
263
264 Particularly, if you are running an Apache server, you can use Apache mode instead. This mode doesn't write any files to your web root folder.
265
266 Just set string "apache" as the second argument and it will force use of apache plugin automatically.
267
268 ```sh
269 acme.sh --issue --apache -d example.com -d www.example.com -d cp.example.com
270 ```
271
272 **This apache mode is only to issue the cert, it will not change your apache config files.
273 You will need to configure your website config files to use the cert by yourself.
274 We don't want to mess with your apache server, don't worry.**
275
276 More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert
277
278 # 7. Use Nginx mode
279
280 **(requires you to be root/sudoer, since it is required to interact with Nginx server)**
281
282 If you are running a web server, it is recommended to use the `Webroot mode`.
283
284 Particularly, if you are running an nginx server, you can use nginx mode instead. This mode doesn't write any files to your web root folder.
285
286 Just set string "nginx" as the second argument.
287
288 It will configure nginx server automatically to verify the domain and then restore the nginx config to the original version.
289
290 So, the config is not changed.
291
292 ```sh
293 acme.sh --issue --nginx -d example.com -d www.example.com -d cp.example.com
294 ```
295
296 **This nginx mode is only to issue the cert, it will not change your nginx config files.
297 You will need to configure your website config files to use the cert by yourself.
298 We don't want to mess with your nginx server, don't worry.**
299
300 More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert
301
302 # 8. Automatic DNS API integration
303
304 If your DNS provider supports API access, we can use that API to automatically issue the certs.
305
306 You don't have to do anything manually!
307
308 ### Currently acme.sh supports most of the dns providers:
309
310 https://github.com/acmesh-official/acme.sh/wiki/dnsapi
311
312 # 9. Use DNS manual mode:
313
314 See: https://github.com/acmesh-official/acme.sh/wiki/dns-manual-mode first.
315
316 If your dns provider doesn't support any api access, you can add the txt record by hand.
317
318 ```bash
319 acme.sh --issue --dns -d example.com -d www.example.com -d cp.example.com
320 ```
321
322 You should get an output like below:
323
324 ```sh
325 Add the following txt record:
326 Domain:_acme-challenge.example.com
327 Txt value:9ihDbjYfTExAYeDs4DBUeuTo18KBzwvTEjUnSwd32-c
328
329 Add the following txt record:
330 Domain:_acme-challenge.www.example.com
331 Txt value:9ihDbjxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
332
333 Please add those txt records to the domains. Waiting for the dns to take effect.
334 ```
335
336 Then just rerun with `renew` argument:
337
338 ```bash
339 acme.sh --renew -d example.com
340 ```
341
342 Ok, it's done.
343
344 **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.**
345
346 **Please use dns api mode instead.**
347
348 # 10. Issue ECC certificates
349
350 `Let's Encrypt` can now issue **ECDSA** certificates.
351
352 And we support them too!
353
354 Just set the `keylength` parameter with a prefix `ec-`.
355
356 For example:
357
358 ### Single domain ECC certificate
359
360 ```bash
361 acme.sh --issue -w /home/wwwroot/example.com -d example.com --keylength ec-256
362 ```
363
364 ### SAN multi domain ECC certificate
365
366 ```bash
367 acme.sh --issue -w /home/wwwroot/example.com -d example.com -d www.example.com --keylength ec-256
368 ```
369
370 Please look at the `keylength` parameter above.
371
372 Valid values are:
373
374 1. **ec-256 (prime256v1, "ECDSA P-256")**
375 2. **ec-384 (secp384r1, "ECDSA P-384")**
376 3. **ec-521 (secp521r1, "ECDSA P-521", which is not supported by Let's Encrypt yet.)**
377
378
379
380 # 11. Issue Wildcard certificates
381
382 It's simple, just give a wildcard domain as the `-d` parameter.
383
384 ```sh
385 acme.sh --issue -d example.com -d '*.example.com' --dns dns_cf
386 ```
387
388
389
390 # 12. How to renew the certs
391
392 No, you don't need to renew the certs manually. All the certs will be renewed automatically every **60** days.
393
394 However, you can also force to renew a cert:
395
396 ```sh
397 acme.sh --renew -d example.com --force
398 ```
399
400 or, for ECC cert:
401
402 ```sh
403 acme.sh --renew -d example.com --force --ecc
404 ```
405
406
407 # 13. How to stop cert renewal
408
409 To stop renewal of a cert, you can execute the following to remove the cert from the renewal list:
410
411 ```sh
412 acme.sh --remove -d example.com [--ecc]
413 ```
414
415 The cert/key file is not removed from the disk.
416
417 You can remove the respective directory (e.g. `~/.acme.sh/example.com`) by yourself.
418
419
420 # 14. How to upgrade `acme.sh`
421
422 acme.sh is in constant development, so it's strongly recommended to use the latest code.
423
424 You can update acme.sh to the latest code:
425
426 ```sh
427 acme.sh --upgrade
428 ```
429
430 You can also enable auto upgrade:
431
432 ```sh
433 acme.sh --upgrade --auto-upgrade
434 ```
435
436 Then **acme.sh** will be kept up to date automatically.
437
438 Disable auto upgrade:
439
440 ```sh
441 acme.sh --upgrade --auto-upgrade 0
442 ```
443
444
445 # 15. Issue a cert from an existing CSR
446
447 https://github.com/acmesh-official/acme.sh/wiki/Issue-a-cert-from-existing-CSR
448
449
450 # 16. Send notifications in cronjob
451
452 https://github.com/acmesh-official/acme.sh/wiki/notify
453
454
455 # 17. Under the Hood
456
457 Speak ACME language using shell, directly to "Let's Encrypt".
458
459 TODO:
460
461
462 # 18. Acknowledgments
463
464 1. Acme-tiny: https://github.com/diafygi/acme-tiny
465 2. ACME protocol: https://github.com/ietf-wg-acme/acme
466
467
468 ## Contributors
469
470 ### Code Contributors
471
472 This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
473 <a href="https://github.com/acmesh-official/acme.sh/graphs/contributors"><img src="https://opencollective.com/acmesh/contributors.svg?width=890&button=false" /></a>
474
475 ### Financial Contributors
476
477 Become a financial contributor and help us sustain our community. [[Contribute](https://opencollective.com/acmesh/contribute)]
478
479 #### Individuals
480
481 <a href="https://opencollective.com/acmesh"><img src="https://opencollective.com/acmesh/individuals.svg?width=890"></a>
482
483 #### Organizations
484
485 Support this project with your organization. Your logo will show up here with a link to your website. [[Contribute](https://opencollective.com/acmesh/contribute)]
486
487 <a href="https://opencollective.com/acmesh/organization/0/website"><img src="https://opencollective.com/acmesh/organization/0/avatar.svg"></a>
488 <a href="https://opencollective.com/acmesh/organization/1/website"><img src="https://opencollective.com/acmesh/organization/1/avatar.svg"></a>
489 <a href="https://opencollective.com/acmesh/organization/2/website"><img src="https://opencollective.com/acmesh/organization/2/avatar.svg"></a>
490 <a href="https://opencollective.com/acmesh/organization/3/website"><img src="https://opencollective.com/acmesh/organization/3/avatar.svg"></a>
491 <a href="https://opencollective.com/acmesh/organization/4/website"><img src="https://opencollective.com/acmesh/organization/4/avatar.svg"></a>
492 <a href="https://opencollective.com/acmesh/organization/5/website"><img src="https://opencollective.com/acmesh/organization/5/avatar.svg"></a>
493 <a href="https://opencollective.com/acmesh/organization/6/website"><img src="https://opencollective.com/acmesh/organization/6/avatar.svg"></a>
494 <a href="https://opencollective.com/acmesh/organization/7/website"><img src="https://opencollective.com/acmesh/organization/7/avatar.svg"></a>
495 <a href="https://opencollective.com/acmesh/organization/8/website"><img src="https://opencollective.com/acmesh/organization/8/avatar.svg"></a>
496 <a href="https://opencollective.com/acmesh/organization/9/website"><img src="https://opencollective.com/acmesh/organization/9/avatar.svg"></a>
497
498 # 19. License & Others
499
500 License is GPLv3
501
502 Please Star and Fork me.
503
504 [Issues](https://github.com/acmesh-official/acme.sh/issues) and [pull requests](https://github.com/acmesh-official/acme.sh/pulls) are welcome.
505
506
507 # 20. Donate
508 Your donation makes **acme.sh** better:
509
510 1. PayPal/Alipay(支付宝)/Wechat(微信): [https://donate.acme.sh/](https://donate.acme.sh/)
511
512 [Donate List](https://github.com/acmesh-official/acme.sh/wiki/Donate-list)