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 # [中文说明](https://github.com/Neilpang/acme.sh/wiki/%E8%AF%B4%E6%98%8E)
  17
  18
  19 # Tested OS
  20
  21 | NO | Status| Platform|
  22 |----|-------|---------|
  23 |1|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/ubuntu-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)| Ubuntu
  24 |2|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/debian-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)| Debian
  25 |3|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/centos-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|CentOS
  26 |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)
  27 |5|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/freebsd.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|FreeBSD
  28 |6|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/pfsense.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|pfsense
  29 |7|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/opensuse-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|openSUSE
  30 |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)
  31 |9|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/base-archlinux.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|Archlinux
  32 |10|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/fedora-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|fedora
  33 |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
  34 |12|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/oraclelinux-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|Oracle Linux
  35 |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
  36 |14|-----| Cloud Linux  https://github.com/Neilpang/le/issues/111
  37 |15|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/openbsd.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|OpenBSD
  38 |16|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/mageia.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|Mageia
  39 |17|-----| OpenWRT: Tested and working. See [wiki page](https://github.com/Neilpang/acme.sh/wiki/How-to-run-on-OpenWRT)
  40 |18|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/solaris.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|SunOS/Solaris
  41 |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
  42
  43 For all build statuses, check our [daily build project](https://github.com/Neilpang/acmetest):
  44
  45 https://github.com/Neilpang/acmetest
  46
  47
  48 # Supported modes
  49
  50 - Webroot mode
  51 - Standalone mode
  52 - Apache mode
  53 - DNS mode
  54
  55
  56 # 1. How to install
  57
  58 ### 1. Install online
  59
  60 Check this project: https://github.com/Neilpang/get.acme.sh
  61
  62 ```bash
  63 curl https://get.acme.sh | sh
  64 ```
  65
  66 Or:
  67
  68 ```bash
  69 wget -O -  https://get.acme.sh | sh
  70 ```
  71
  72
  73 ### 2. Or, Install from git
  74
  75 Clone this project and launch installation:
  76
  77 ```bash
  78 git clone https://github.com/Neilpang/acme.sh.git
  79 cd ./acme.sh
  80 ./acme.sh --install
  81 ```
  82
  83 You `don't have to be root` then, although `it is recommended`.
  84
  85 Advanced Installation: https://github.com/Neilpang/acme.sh/wiki/How-to-install
  86
  87 The installer will perform 3 actions:
  88
  89 1. Create and copy `acme.sh` to your home dir (`$HOME`): `~/.acme.sh/`.
  90 All certs will be placed in this folder too.
  91 2. Create alias for: `acme.sh=~/.acme.sh/acme.sh`.
  92 3. Create daily cron job to check and renew the certs if needed.
  93
  94 Cron entry example:
  95
  96 ```bash
  97 0 0 * * * "/home/user/.acme.sh"/acme.sh --cron --home "/home/user/.acme.sh" > /dev/null
  98 ```
  99
 100 After the installation, you must close the current terminal and reopen it to make the alias take effect.
 101
 102 Ok, you are ready to issue certs now.
 103
 104 Show help message:
 105
 106 ```
 107 root@v1:~# acme.sh -h
 108 ```
 109
 110 # 2. Just issue a cert
 111
 112 **Example 1:** Single domain.
 113
 114 ```bash
 115 acme.sh --issue -d example.com -w /home/wwwroot/example.com
 116 ```
 117
 118 **Example 2:** Multiple domains in the same cert.
 119
 120 ```bash
 121 acme.sh --issue -d example.com -d www.example.com -d cp.example.com -w /home/wwwroot/example.com
 122 ```
 123
 124 The parameter `/home/wwwroot/example.com` is the web root folder. You **MUST** have `write access` to this folder.
 125
 126 Second argument **"example.com"** is the main domain you want to issue the cert for.
 127 You must have at least one domain there.
 128
 129 You must point and bind all the domains to the same webroot dir: `/home/wwwroot/example.com`.
 130
 131 Generated/issued certs will be placed in `~/.acme.sh/example.com/`
 132
 133 The issued cert will be renewed automatically every **60** days.
 134
 135 More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert
 136
 137
 138 # 3. Install the issued cert to Apache/Nginx etc.
 139
 140 After you issue a cert, you probably want to install/copy the cert to your Apache/Nginx or other servers.
 141 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.
 142
 143 **Apache** example:
 144 ```bash
 145 acme.sh --installcert -d example.com \
 146 --certpath      /path/to/certfile/in/apache/cert.pem  \
 147 --keypath       /path/to/keyfile/in/apache/key.pem  \
 148 --fullchainpath /path/to/fullchain/certfile/apache/fullchain.pem \
 149 --reloadcmd     "service apache2 restart"
 150 ```
 151
 152 **Nginx** example:
 153 ```bash
 154 acme.sh --installcert -d example.com \
 155 --keypath       /path/to/keyfile/in/nginx/key.pem  \
 156 --fullchainpath /path/to/fullchain/nginx/cert.pem \
 157 --reloadcmd     "service nginx restart"
 158 ```
 159
 160 Only the domain is required, all the other parameters are optional.
 161
 162 Install/copy the issued cert/key to the production Apache or Nginx path.
 163
 164 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`.
 165
 166
 167 # 4. Use Standalone server to issue cert
 168
 169 **(requires you to be root/sudoer or have permission to listen on port 80 (TCP))**
 170
 171 Port `80` (TCP) **MUST** be free to listen on, otherwise you will be prompted to free it and try again.
 172
 173 ```bash
 174 acme.sh --issue --standalone -d example.com -d www.example.com -d cp.example.com
 175 ```
 176
 177 More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert
 178
 179
 180 # 5. Use Standalone TLS server to issue cert
 181
 182 **(requires you to be root/sudoer or have permission to listen on port 443 (TCP))**
 183
 184 acme.sh supports `tls-sni-01` validation.
 185
 186 Port `443` (TCP) **MUST** be free to listen on, otherwise you will be prompted to free it and try again.
 187
 188 ```bash
 189 acme.sh --issue --tls -d example.com -d www.example.com -d cp.example.com
 190 ```
 191
 192 More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert
 193
 194
 195 # 6. Use Apache mode
 196
 197 **(requires you to be root/sudoer, since it is required to interact with Apache server)**
 198
 199 If you are running a web server, Apache or Nginx, it is recommended to use the `Webroot mode`.
 200
 201 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.
 202
 203 Just set string "apache" as the second argument and it will force use of apache plugin automatically.
 204
 205 ```
 206 acme.sh --issue --apache -d example.com -d www.example.com -d cp.example.com
 207 ```
 208
 209 More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert
 210
 211
 212 # 7. Use DNS mode:
 213
 214 Support the `dns-01` challenge.
 215
 216 ```bash
 217 acme.sh --issue --dns -d example.com -d www.example.com -d cp.example.com
 218 ```
 219
 220 You should get an output like below:
 221
 222 ```
 223 Add the following txt record:
 224 Domain:_acme-challenge.example.com
 225 Txt value:9ihDbjYfTExAYeDs4DBUeuTo18KBzwvTEjUnSwd32-c
 226
 227 Add the following txt record:
 228 Domain:_acme-challenge.www.example.com
 229 Txt value:9ihDbjxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 230
 231 Please add those txt records to the domains. Waiting for the dns to take effect.
 232 ```
 233
 234 Then just rerun with `renew` argument:
 235
 236 ```bash
 237 acme.sh --renew -d example.com
 238 ```
 239
 240 Ok, it's finished.
 241
 242
 243 # 8. Automatic DNS API integration
 244
 245 If your DNS provider supports API access, we can use that API to automatically issue the certs.
 246
 247 You don't have to do anything manually!
 248
 249 ### Currently acme.sh supports:
 250
 251 1. CloudFlare.com API
 252 1. DNSPod.cn API
 253 1. CloudXNS.com API
 254 1. GoDaddy.com API
 255 1. OVH, kimsufi, soyoustart and runabove API
 256 1. AWS Route 53
 257 1. PowerDNS.com API
 258 1. lexicon DNS API: https://github.com/Neilpang/acme.sh/wiki/How-to-use-lexicon-dns-api
 259    (DigitalOcean, DNSimple, DNSMadeEasy, DNSPark, EasyDNS, Namesilo, NS1, PointHQ, Rage4 and Vultr etc.)
 260 1. LuaDNS.com API
 261 1. DNSMadeEasy.com API
 262 1. nsupdate API
 263
 264 **More APIs coming soon...**
 265
 266 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.
 267
 268 For more details: [How to use DNS API](dnsapi)
 269
 270
 271 # 9. Issue ECC certificates
 272
 273 `Let's Encrypt` can now issue **ECDSA** certificates.
 274
 275 And we support them too!
 276
 277 Just set the `length` parameter with a prefix `ec-`.
 278
 279 For example:
 280
 281 ### Single domain ECC cerfiticate
 282
 283 ```bash
 284 acme.sh --issue -w /home/wwwroot/example.com -d example.com --keylength ec-256
 285 ```
 286
 287 ### SAN multi domain ECC certificate
 288
 289 ```bash
 290 acme.sh --issue -w /home/wwwroot/example.com -d example.com -d www.example.com --keylength ec-256
 291 ```
 292
 293 Please look at the last parameter above.
 294
 295 Valid values are:
 296
 297 1. **ec-256 (prime256v1, "ECDSA P-256")**
 298 2. **ec-384 (secp384r1,  "ECDSA P-384")**
 299 3. **ec-521 (secp521r1,  "ECDSA P-521", which is not supported by Let's Encrypt yet.)**
 300
 301
 302 # 10. How to renew the issued certs
 303
 304 No, you don't need to renew the certs manually. All the certs will be renewed automatically every **60** days.
 305
 306 However, you can also force to renew any cert:
 307
 308 ```
 309 acme.sh --renew -d example.com --force
 310 ```
 311
 312 or, for ECC cert:
 313
 314 ```
 315 acme.sh --renew -d example.com --force --ecc
 316 ```
 317
 318
 319 # 11. How to upgrade `acme.sh`
 320
 321 acme.sh is in constant developement, so it's strongly recommended to use the latest code.
 322
 323 You can update acme.sh to the latest code:
 324
 325 ```
 326 acme.sh --upgrade
 327 ```
 328
 329 You can also enable auto upgrade:
 330
 331 ```
 332 acme.sh --upgrade --auto-upgrade
 333 ```
 334
 335 Then **acme.sh** will be kept up to date automatically.
 336
 337 Disable auto upgrade:
 338
 339 ```
 340 acme.sh --upgrade --auto-upgrade 0
 341 ```
 342
 343
 344 # 12. Issue a cert from an existing CSR
 345
 346 https://github.com/Neilpang/acme.sh/wiki/Issue-a-cert-from-existing-CSR
 347
 348
 349 # Under the Hood
 350
 351 Speak ACME language using shell, directly to "Let's Encrypt".
 352
 353 TODO:
 354
 355
 356 # Acknowledgments
 357
 358 1. Acme-tiny: https://github.com/diafygi/acme-tiny
 359 2. ACME protocol: https://github.com/ietf-wg-acme/acme
 360 3. Certbot: https://github.com/certbot/certbot
 361
 362
 363 # License & Others
 364
 365 License is GPLv3
 366
 367 Please Star and Fork me.
 368
 369 [Issues](https://github.com/Neilpang/acme.sh/issues) and [pull requests](https://github.com/Neilpang/acme.sh/pulls) are welcome.
 370
 371
 372 # Donate
 373
 374 1. PayPal: donate@acme.sh
 375
 376 [Donate List](https://github.com/Neilpang/acme.sh/wiki/Donate-list)