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