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