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