README.md

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