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