]> git.proxmox.com Git - mirror_acme.sh.git/blob - README.md
fix https://github.com/acmesh-official/acme.sh/issues/3252
[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|[![Ubuntu](https://github.com/acmesh-official/acme.sh/workflows/LetsEncrypt/badge.svg)](https://github.com/acmesh-official/acme.sh/actions?query=workflow%3ALetsEncrypt)| Ubuntu
64 |5|[![](https://acmesh-official.github.io/acmetest/status/pfsense.svg)](https://github.com/acmesh-official/acmetest#here-are-the-latest-status)|pfsense
65 |6|[![](https://acmesh-official.github.io/acmetest/status/openbsd.svg)](https://github.com/acmesh-official/acmetest#here-are-the-latest-status)|OpenBSD
66 |7|[![](https://acmesh-official.github.io/acmetest/status/solaris.svg)](https://github.com/acmesh-official/acmetest#here-are-the-latest-status)|SunOS/Solaris
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
93 # Supported modes
94
95 - Webroot mode
96 - Standalone mode
97 - Standalone tls-alpn mode
98 - Apache mode
99 - Nginx mode
100 - DNS mode
101 - [DNS alias mode](https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode)
102 - [Stateless mode](https://github.com/acmesh-official/acme.sh/wiki/Stateless-Mode)
103
104
105 # 1. How to install
106
107 ### 1. Install online
108
109 Check this project: https://github.com/acmesh-official/get.acme.sh
110
111 ```bash
112 curl https://get.acme.sh | sh
113 ```
114
115 Or:
116
117 ```bash
118 wget -O - https://get.acme.sh | sh
119 ```
120
121
122 ### 2. Or, Install from git
123
124 Clone this project and launch installation:
125
126 ```bash
127 git clone https://github.com/acmesh-official/acme.sh.git
128 cd ./acme.sh
129 ./acme.sh --install
130 ```
131
132 You `don't have to be root` then, although `it is recommended`.
133
134 Advanced Installation: https://github.com/acmesh-official/acme.sh/wiki/How-to-install
135
136 The installer will perform 3 actions:
137
138 1. Create and copy `acme.sh` to your home dir (`$HOME`): `~/.acme.sh/`.
139 All certs will be placed in this folder too.
140 2. Create alias for: `acme.sh=~/.acme.sh/acme.sh`.
141 3. Create daily cron job to check and renew the certs if needed.
142
143 Cron entry example:
144
145 ```bash
146 0 0 * * * "/home/user/.acme.sh"/acme.sh --cron --home "/home/user/.acme.sh" > /dev/null
147 ```
148
149 After the installation, you must close the current terminal and reopen it to make the alias take effect.
150
151 Ok, you are ready to issue certs now.
152
153 Show help message:
154
155 ```sh
156 root@v1:~# acme.sh -h
157 ```
158
159 # 2. Just issue a cert
160
161 **Example 1:** Single domain.
162
163 ```bash
164 acme.sh --issue -d example.com -w /home/wwwroot/example.com
165 ```
166
167 or:
168
169 ```bash
170 acme.sh --issue -d example.com -w /home/username/public_html
171 ```
172
173 or:
174
175 ```bash
176 acme.sh --issue -d example.com -w /var/www/html
177 ```
178
179 **Example 2:** Multiple domains in the same cert.
180
181 ```bash
182 acme.sh --issue -d example.com -d www.example.com -d cp.example.com -w /home/wwwroot/example.com
183 ```
184
185 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.
186
187 Second argument **"example.com"** is the main domain you want to issue the cert for.
188 You must have at least one domain there.
189
190 You must point and bind all the domains to the same webroot dir: `/home/wwwroot/example.com`.
191
192 The certs will be placed in `~/.acme.sh/example.com/`
193
194 The certs will be renewed automatically every **60** days.
195
196 More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert
197
198
199 # 3. Install the cert to Apache/Nginx etc.
200
201 After the cert is generated, you probably want to install/copy the cert to your Apache/Nginx or other servers.
202 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.
203
204 **Apache** example:
205 ```bash
206 acme.sh --install-cert -d example.com \
207 --cert-file /path/to/certfile/in/apache/cert.pem \
208 --key-file /path/to/keyfile/in/apache/key.pem \
209 --fullchain-file /path/to/fullchain/certfile/apache/fullchain.pem \
210 --reloadcmd "service apache2 force-reload"
211 ```
212
213 **Nginx** example:
214 ```bash
215 acme.sh --install-cert -d example.com \
216 --key-file /path/to/keyfile/in/nginx/key.pem \
217 --fullchain-file /path/to/fullchain/nginx/cert.pem \
218 --reloadcmd "service nginx force-reload"
219 ```
220
221 Only the domain is required, all the other parameters are optional.
222
223 The ownership and permission info of existing files are preserved. You can pre-create the files to define the ownership and permission.
224
225 Install/copy the cert/key to the production Apache or Nginx path.
226
227 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`.
228
229
230 **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.**
231
232 # 4. Use Standalone server to issue cert
233
234 **(requires you to be root/sudoer or have permission to listen on port 80 (TCP))**
235
236 Port `80` (TCP) **MUST** be free to listen on, otherwise you will be prompted to free it and try again.
237
238 ```bash
239 acme.sh --issue --standalone -d example.com -d www.example.com -d cp.example.com
240 ```
241
242 More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert
243
244 # 5. Use Standalone ssl server to issue cert
245
246 **(requires you to be root/sudoer or have permission to listen on port 443 (TCP))**
247
248 Port `443` (TCP) **MUST** be free to listen on, otherwise you will be prompted to free it and try again.
249
250 ```bash
251 acme.sh --issue --alpn -d example.com -d www.example.com -d cp.example.com
252 ```
253
254 More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert
255
256
257 # 6. Use Apache mode
258
259 **(requires you to be root/sudoer, since it is required to interact with Apache server)**
260
261 If you are running a web server, it is recommended to use the `Webroot mode`.
262
263 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.
264
265 Just set string "apache" as the second argument and it will force use of apache plugin automatically.
266
267 ```sh
268 acme.sh --issue --apache -d example.com -d www.example.com -d cp.example.com
269 ```
270
271 **This apache mode is only to issue the cert, it will not change your apache config files.
272 You will need to configure your website config files to use the cert by yourself.
273 We don't want to mess with your apache server, don't worry.**
274
275 More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert
276
277 # 7. Use Nginx mode
278
279 **(requires you to be root/sudoer, since it is required to interact with Nginx server)**
280
281 If you are running a web server, it is recommended to use the `Webroot mode`.
282
283 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.
284
285 Just set string "nginx" as the second argument.
286
287 It will configure nginx server automatically to verify the domain and then restore the nginx config to the original version.
288
289 So, the config is not changed.
290
291 ```sh
292 acme.sh --issue --nginx -d example.com -d www.example.com -d cp.example.com
293 ```
294
295 **This nginx mode is only to issue the cert, it will not change your nginx config files.
296 You will need to configure your website config files to use the cert by yourself.
297 We don't want to mess with your nginx server, don't worry.**
298
299 More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert
300
301 # 8. Automatic DNS API integration
302
303 If your DNS provider supports API access, we can use that API to automatically issue the certs.
304
305 You don't have to do anything manually!
306
307 ### Currently acme.sh supports most of the dns providers:
308
309 https://github.com/acmesh-official/acme.sh/wiki/dnsapi
310
311 # 9. Use DNS manual mode:
312
313 See: https://github.com/acmesh-official/acme.sh/wiki/dns-manual-mode first.
314
315 If your dns provider doesn't support any api access, you can add the txt record by hand.
316
317 ```bash
318 acme.sh --issue --dns -d example.com -d www.example.com -d cp.example.com
319 ```
320
321 You should get an output like below:
322
323 ```sh
324 Add the following txt record:
325 Domain:_acme-challenge.example.com
326 Txt value:9ihDbjYfTExAYeDs4DBUeuTo18KBzwvTEjUnSwd32-c
327
328 Add the following txt record:
329 Domain:_acme-challenge.www.example.com
330 Txt value:9ihDbjxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
331
332 Please add those txt records to the domains. Waiting for the dns to take effect.
333 ```
334
335 Then just rerun with `renew` argument:
336
337 ```bash
338 acme.sh --renew -d example.com
339 ```
340
341 Ok, it's done.
342
343 **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.**
344
345 **Please use dns api mode instead.**
346
347 # 10. Issue ECC certificates
348
349 `Let's Encrypt` can now issue **ECDSA** certificates.
350
351 And we support them too!
352
353 Just set the `keylength` parameter with a prefix `ec-`.
354
355 For example:
356
357 ### Single domain ECC certificate
358
359 ```bash
360 acme.sh --issue -w /home/wwwroot/example.com -d example.com --keylength ec-256
361 ```
362
363 ### SAN multi domain ECC certificate
364
365 ```bash
366 acme.sh --issue -w /home/wwwroot/example.com -d example.com -d www.example.com --keylength ec-256
367 ```
368
369 Please look at the `keylength` parameter above.
370
371 Valid values are:
372
373 1. **ec-256 (prime256v1, "ECDSA P-256")**
374 2. **ec-384 (secp384r1, "ECDSA P-384")**
375 3. **ec-521 (secp521r1, "ECDSA P-521", which is not supported by Let's Encrypt yet.)**
376
377
378
379 # 11. Issue Wildcard certificates
380
381 It's simple, just give a wildcard domain as the `-d` parameter.
382
383 ```sh
384 acme.sh --issue -d example.com -d '*.example.com' --dns dns_cf
385 ```
386
387
388
389 # 12. How to renew the certs
390
391 No, you don't need to renew the certs manually. All the certs will be renewed automatically every **60** days.
392
393 However, you can also force to renew a cert:
394
395 ```sh
396 acme.sh --renew -d example.com --force
397 ```
398
399 or, for ECC cert:
400
401 ```sh
402 acme.sh --renew -d example.com --force --ecc
403 ```
404
405
406 # 13. How to stop cert renewal
407
408 To stop renewal of a cert, you can execute the following to remove the cert from the renewal list:
409
410 ```sh
411 acme.sh --remove -d example.com [--ecc]
412 ```
413
414 The cert/key file is not removed from the disk.
415
416 You can remove the respective directory (e.g. `~/.acme.sh/example.com`) by yourself.
417
418
419 # 14. How to upgrade `acme.sh`
420
421 acme.sh is in constant development, so it's strongly recommended to use the latest code.
422
423 You can update acme.sh to the latest code:
424
425 ```sh
426 acme.sh --upgrade
427 ```
428
429 You can also enable auto upgrade:
430
431 ```sh
432 acme.sh --upgrade --auto-upgrade
433 ```
434
435 Then **acme.sh** will be kept up to date automatically.
436
437 Disable auto upgrade:
438
439 ```sh
440 acme.sh --upgrade --auto-upgrade 0
441 ```
442
443
444 # 15. Issue a cert from an existing CSR
445
446 https://github.com/acmesh-official/acme.sh/wiki/Issue-a-cert-from-existing-CSR
447
448
449 # 16. Send notifications in cronjob
450
451 https://github.com/acmesh-official/acme.sh/wiki/notify
452
453
454 # 17. Under the Hood
455
456 Speak ACME language using shell, directly to "Let's Encrypt".
457
458 TODO:
459
460
461 # 18. Acknowledgments
462
463 1. Acme-tiny: https://github.com/diafygi/acme-tiny
464 2. ACME protocol: https://github.com/ietf-wg-acme/acme
465
466
467 ## Contributors
468
469 ### Code Contributors
470
471 This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
472 <a href="https://github.com/acmesh-official/acme.sh/graphs/contributors"><img src="https://opencollective.com/acmesh/contributors.svg?width=890&button=false" /></a>
473
474 ### Financial Contributors
475
476 Become a financial contributor and help us sustain our community. [[Contribute](https://opencollective.com/acmesh/contribute)]
477
478 #### Individuals
479
480 <a href="https://opencollective.com/acmesh"><img src="https://opencollective.com/acmesh/individuals.svg?width=890"></a>
481
482 #### Organizations
483
484 Support this project with your organization. Your logo will show up here with a link to your website. [[Contribute](https://opencollective.com/acmesh/contribute)]
485
486 <a href="https://opencollective.com/acmesh/organization/0/website"><img src="https://opencollective.com/acmesh/organization/0/avatar.svg"></a>
487 <a href="https://opencollective.com/acmesh/organization/1/website"><img src="https://opencollective.com/acmesh/organization/1/avatar.svg"></a>
488 <a href="https://opencollective.com/acmesh/organization/2/website"><img src="https://opencollective.com/acmesh/organization/2/avatar.svg"></a>
489 <a href="https://opencollective.com/acmesh/organization/3/website"><img src="https://opencollective.com/acmesh/organization/3/avatar.svg"></a>
490 <a href="https://opencollective.com/acmesh/organization/4/website"><img src="https://opencollective.com/acmesh/organization/4/avatar.svg"></a>
491 <a href="https://opencollective.com/acmesh/organization/5/website"><img src="https://opencollective.com/acmesh/organization/5/avatar.svg"></a>
492 <a href="https://opencollective.com/acmesh/organization/6/website"><img src="https://opencollective.com/acmesh/organization/6/avatar.svg"></a>
493 <a href="https://opencollective.com/acmesh/organization/7/website"><img src="https://opencollective.com/acmesh/organization/7/avatar.svg"></a>
494 <a href="https://opencollective.com/acmesh/organization/8/website"><img src="https://opencollective.com/acmesh/organization/8/avatar.svg"></a>
495 <a href="https://opencollective.com/acmesh/organization/9/website"><img src="https://opencollective.com/acmesh/organization/9/avatar.svg"></a>
496
497 # 19. License & Others
498
499 License is GPLv3
500
501 Please Star and Fork me.
502
503 [Issues](https://github.com/acmesh-official/acme.sh/issues) and [pull requests](https://github.com/acmesh-official/acme.sh/pulls) are welcome.
504
505
506 # 20. Donate
507 Your donation makes **acme.sh** better:
508
509 1. PayPal/Alipay(支付宝)/Wechat(微信): [https://donate.acme.sh/](https://donate.acme.sh/)
510
511 [Donate List](https://github.com/acmesh-official/acme.sh/wiki/Donate-list)