README.md

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