README.md

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