]>
Commit | Line | Data |
---|---|---|
2b45dba5 | 1 | # An ACME Shell script: acme.sh |
99dc89c0 | 2 | - An ACME protocol client written purely in Shell (Unix shell) language. |
2b45dba5 SF |
3 | - Fully ACME protocol implementation. |
4 | - Simple, powerful and very easy to use. You only need 3 minutes to learn. | |
6de38fbf | 5 | - Bash, dash and sh compatible. |
2b45dba5 | 6 | - Simplest shell script for Let's Encrypt free certificate client. |
99dc89c0 | 7 | - Purely written in Shell with no dependencies on python or Let's Encrypt official client. |
2b45dba5 | 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 N |
12 | |
13 | ||
6cc11ffb | 14 | Wiki: https://github.com/Neilpang/acme.sh/wiki |
de9fd54e | 15 | |
fe04faf6 | 16 | # [中文说明](https://github.com/Neilpang/acme.sh/wiki/%E8%AF%B4%E6%98%8E) |
17 | ||
7a894c4c | 18 | #Tested OS |
daf56504 | 19 | | NO | Status| Platform| |
20 | |----|-------|---------| | |
620f8613 | 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 | |
990d46d6 | 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) |
620f8613 | 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 | |
63c6a3b0 | 34 | |14|-----| Cloud Linux https://github.com/Neilpang/le/issues/111 |
620f8613 | 35 | |15|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/openbsd.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|OpenBSD |
199067e8 | 36 | |16|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/mageia.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|Mageia |
3ad08e95 | 37 | |17|-----| OpenWRT: Tested and working. See [wiki page](https://github.com/Neilpang/acme.sh/wiki/How-to-run-on-OpenWRT) |
527dd31c | 38 | |18|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/solaris.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|SunOS/Solaris |
fb3be850 | 39 | |18|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/gentoo-stage3-amd64.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|Gentoo Linux |
6c0ab5d2 | 40 | |
2b45dba5 | 41 | For all build statuses, check our [daily build project](https://github.com/Neilpang/acmetest): |
6c0ab5d2 | 42 | |
6cc11ffb | 43 | https://github.com/Neilpang/acmetest |
07f4ec4f | 44 | |
2b45dba5 SF |
45 | # Supported Mode |
46 | ||
2c75b3fd | 47 | 1. Webroot mode |
48 | 2. Standalone mode | |
49 | 3. Apache mode | |
52639149 | 50 | 4. Dns mode |
2c75b3fd | 51 | |
2b45dba5 | 52 | |
e8cce73a | 53 | |
df1c9d88 | 54 | # 1. How to install |
6c0ab5d2 | 55 | |
65938b73 | 56 | ### 1. Install online: |
6c0ab5d2 | 57 | |
5bdad844 | 58 | Check this project: https://github.com/Neilpang/get.acme.sh |
b0515cf8 | 59 | |
2b45dba5 | 60 | ```bash |
99dc89c0 | 61 | curl https://get.acme.sh | sh |
90dda23f | 62 | |
63 | ``` | |
64 | ||
65 | Or: | |
2b45dba5 SF |
66 | |
67 | ```bash | |
99dc89c0 | 68 | wget -O - https://get.acme.sh | sh |
90dda23f | 69 | |
70 | ``` | |
71 | ||
72 | ||
65938b73 | 73 | ### 2. Or, Install from git: |
2b45dba5 | 74 | |
90dda23f | 75 | Clone this project: |
2b45dba5 SF |
76 | |
77 | ```bash | |
6cc11ffb | 78 | git clone https://github.com/Neilpang/acme.sh.git |
2b45dba5 | 79 | cd ./acme.sh |
6cc11ffb | 80 | ./acme.sh --install |
6c0ab5d2 | 81 | ``` |
90dda23f | 82 | |
2b45dba5 SF |
83 | You `don't have to be root` then, although `it is recommended`. |
84 | ||
d9ded9f3 | 85 | Advanced Installation: https://github.com/Neilpang/acme.sh/wiki/How-to-install |
86 | ||
2b45dba5 | 87 | The installer will perform 3 actions: |
7a894c4c | 88 | |
2b45dba5 SF |
89 | 1. Create and copy `acme.sh` to your home dir (`$HOME`): `~/.acme.sh/`. |
90 | All certs will be placed in this folder. | |
5bdad844 | 91 | 2. Create alias for: `acme.sh=~/.acme.sh/acme.sh`. |
2b45dba5 SF |
92 | 3. Create everyday cron job to check and renew the cert 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 | ``` | |
acc1e53a | 99 | |
2b45dba5 | 100 | After the installation, you must close current terminal and reopen again to make the alias take effect. |
acc1e53a | 101 | |
cbb5f7ec | 102 | Ok, you are ready to issue cert now. |
6c0ab5d2 | 103 | Show help message: |
2b45dba5 | 104 | |
6c0ab5d2 | 105 | ``` |
39c8f79f | 106 | |
107 | root@v1:~# acme.sh -h | |
93c9216b | 108 | |
6c0ab5d2 N |
109 | ``` |
110 | ||
df1c9d88 | 111 | # 2. Just issue a cert: |
2400e41f | 112 | |
2b45dba5 | 113 | **Example 1:** Single domain. |
2400e41f | 114 | |
2b45dba5 | 115 | ```bash |
caa2e45a | 116 | acme.sh --issue -d example.com -w /home/wwwroot/example.com |
6c0ab5d2 | 117 | ``` |
2b45dba5 SF |
118 | |
119 | **Example 2:** Multiple domains in the same cert. | |
120 | ||
121 | ```bash | |
caa2e45a | 122 | acme.sh --issue -d example.com -d www.example.com -d cp.example.com -w /home/wwwroot/example.com |
6c0ab5d2 | 123 | ``` |
2400e41f | 124 | |
caa2e45a | 125 | The parameter `/home/wwwroot/example.com` is the web root folder. You **MUST** have `write access` to this folder. |
6c0ab5d2 | 126 | |
caa2e45a | 127 | Second argument **"example.com"** is the main domain you want to issue cert for. |
2b45dba5 | 128 | You must have at least a domain there. |
6c0ab5d2 | 129 | |
caa2e45a | 130 | You must point and bind all the domains to the same webroot dir: `/home/wwwroot/example.com`. |
6c0ab5d2 | 131 | |
caa2e45a | 132 | Generate/issued certs will be placed in `~/.acme.sh/example.com/` |
6c0ab5d2 | 133 | |
d2ae7e78 | 134 | The issued cert will be renewed every **60** days automatically. |
6c0ab5d2 | 135 | |
6cc11ffb | 136 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
a63b05a9 | 137 | |
138 | ||
150e9c8a | 139 | # 3. Install the issued cert to apache/nginx etc. |
a63b05a9 | 140 | |
150e9c8a | 141 | After you issue a cert, you probably want to install/copy the cert to your nginx/apache or other servers you may be using. |
2b45dba5 SF |
142 | |
143 | ```bash | |
caa2e45a | 144 | acme.sh --installcert -d example.com \ |
a63b05a9 | 145 | --certpath /path/to/certfile/in/apache/nginx \ |
146 | --keypath /path/to/keyfile/in/apache/nginx \ | |
147 | --capath /path/to/ca/certfile/apache/nginx \ | |
148 | --fullchainpath path/to/fullchain/certfile/apache/nginx \ | |
149 | --reloadcmd "service apache2|nginx reload" | |
6c0ab5d2 | 150 | ``` |
7a894c4c | 151 | |
a63b05a9 | 152 | Only the domain is required, all the other parameters are optional. |
153 | ||
150e9c8a | 154 | Install/copy the issued cert/key to the production apache or nginx path. |
7a894c4c | 155 | |
d2ae7e78 | 156 | 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`. |
6c0ab5d2 | 157 | |
df1c9d88 | 158 | # 4. Use Standalone server to issue cert |
6c0ab5d2 | 159 | |
2b45dba5 | 160 | **(requires you be root/sudoer, or you have permission to listen tcp 80 port)** |
072290f2 | 161 | |
2b45dba5 SF |
162 | The tcp `80` port **MUST** be free to listen, otherwise you will be prompted to free the `80` port and try again. |
163 | ||
164 | ```bash | |
caa2e45a | 165 | acme.sh --issue --standalone -d example.com -d www.example.com -d cp.example.com |
072290f2 N |
166 | ``` |
167 | ||
6cc11ffb | 168 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
a63b05a9 | 169 | |
df1c9d88 | 170 | # 5. Use Standalone tls server to issue cert |
e22bcf7c | 171 | |
172 | **(requires you be root/sudoer, or you have permission to listen tcp 443 port)** | |
173 | ||
174 | acme.sh supports `tls-sni-01` validation. | |
175 | ||
176 | The tcp `443` port **MUST** be free to listen, otherwise you will be prompted to free the `443` port and try again. | |
177 | ||
178 | ```bash | |
caa2e45a | 179 | acme.sh --issue --tls -d example.com -d www.example.com -d cp.example.com |
e22bcf7c | 180 | ``` |
181 | ||
182 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert | |
183 | ||
df1c9d88 | 184 | # 6. Use Apache mode |
2b45dba5 SF |
185 | |
186 | **(requires you be root/sudoer, since it is required to interact with apache server)** | |
187 | ||
188 | If you are running a web server, apache or nginx, it is recommended to use the `Webroot mode`. | |
a63b05a9 | 189 | |
2b45dba5 | 190 | 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 | 191 | |
2b45dba5 | 192 | Just set string "apache" as the second argument, it will force use of apache plugin automatically. |
2c75b3fd | 193 | |
194 | ``` | |
caa2e45a | 195 | acme.sh --issue --apache -d example.com -d www.example.com -d user.example.com |
2c75b3fd | 196 | ``` |
a63b05a9 | 197 | |
6cc11ffb | 198 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
2c75b3fd | 199 | |
df1c9d88 | 200 | # 7. Use DNS mode: |
a947dbc6 | 201 | |
2b45dba5 SF |
202 | Support the `dns-01` challenge. |
203 | ||
204 | ```bash | |
caa2e45a | 205 | acme.sh --issue --dns -d example.com -d www.example.com -d user.example.com |
a947dbc6 N |
206 | ``` |
207 | ||
2b45dba5 SF |
208 | You should get the output like below: |
209 | ||
a947dbc6 N |
210 | ``` |
211 | Add the following txt record: | |
caa2e45a | 212 | Domain:_acme-challenge.example.com |
a947dbc6 N |
213 | Txt value:9ihDbjYfTExAYeDs4DBUeuTo18KBzwvTEjUnSwd32-c |
214 | ||
215 | Add the following txt record: | |
caa2e45a | 216 | Domain:_acme-challenge.www.example.com |
a947dbc6 | 217 | Txt value:9ihDbjxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
a947dbc6 N |
218 | |
219 | Please add those txt records to the domains. Waiting for the dns to take effect. | |
220 | ||
a947dbc6 | 221 | ``` |
2b45dba5 SF |
222 | |
223 | Then just rerun with `renew` argument: | |
224 | ||
225 | ```bash | |
caa2e45a | 226 | acme.sh --renew -d example.com |
a947dbc6 N |
227 | ``` |
228 | ||
229 | Ok, it's finished. | |
230 | ||
df1c9d88 | 231 | # 8. Automatic DNS API integration |
a947dbc6 | 232 | |
2b45dba5 | 233 | If your DNS provider supports API access, we can use API to automatically issue the certs. |
6c0ab5d2 | 234 | |
2b45dba5 | 235 | You don't have do anything manually! |
ab497961 | 236 | |
2b45dba5 | 237 | ### Currently acme.sh supports: |
855d9499 | 238 | |
2b45dba5 SF |
239 | 1. Cloudflare.com API |
240 | 2. Dnspod.cn API | |
241 | 3. Cloudxns.com API | |
30de13b4 | 242 | 4. Godaddy.com API |
36246ad9 | 243 | 5. OVH, kimsufi, soyoustart and runabove API |
244 | 6. AWS Route 53, see: https://github.com/Neilpang/acme.sh/issues/65 | |
483ebc81 | 245 | 7. PowerDNS API |
d6f0c2b5 | 246 | 8. lexicon dns api: https://github.com/Neilpang/acme.sh/wiki/How-to-use-lexicon-dns-api |
2ed01ff0 | 247 | (DigitalOcean, DNSimple, DnsMadeEasy, DNSPark, EasyDNS, Namesilo, NS1, PointHQ, Rage4 and Vultr etc.) |
ab497961 | 248 | |
2b45dba5 | 249 | ##### More APIs are coming soon... |
ab497961 | 250 | |
2b45dba5 | 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. |
ab497961 | 252 | |
855d9499 | 253 | For more details: [How to use dns api](dnsapi) |
ab497961 | 254 | |
df1c9d88 | 255 | # 9. Issue ECC certificate: |
2b45dba5 SF |
256 | |
257 | `Let's Encrypt` now can issue **ECDSA** certificates. | |
258 | ||
1add47a6 | 259 | And we also support it. |
260 | ||
8b92aab7 | 261 | Just set the `length` parameter with a prefix `ec-`. |
2b45dba5 | 262 | |
1add47a6 | 263 | For example: |
9e6c4208 | 264 | |
2b45dba5 | 265 | ### Single domain ECC cerfiticate: |
9e6c4208 | 266 | |
2b45dba5 | 267 | ```bash |
caa2e45a | 268 | acme.sh --issue -w /home/wwwroot/example.com -d example.com --keylength ec-256 |
1add47a6 | 269 | ``` |
2b45dba5 SF |
270 | |
271 | SAN multi domain ECC certificate: | |
272 | ||
273 | ```bash | |
caa2e45a | 274 | acme.sh --issue -w /home/wwwroot/example.com -d example.com -d www.example.com --keylength ec-256 |
9e6c4208 N |
275 | ``` |
276 | ||
1add47a6 | 277 | Please look at the last parameter above. |
278 | ||
279 | Valid values are: | |
280 | ||
2b45dba5 SF |
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.)** | |
1add47a6 | 284 | |
df1c9d88 | 285 | |
286 | # 10. How to renew the cert | |
287 | ||
d2ae7e78 | 288 | No, you don't need to renew the certs manually. All the certs will be renewed automatically every **60** days. |
df1c9d88 | 289 | |
290 | However, you can also force to renew any cert: | |
291 | ||
292 | ``` | |
caa2e45a | 293 | acme.sh --renew -d example.com --force |
df1c9d88 | 294 | ``` |
295 | ||
296 | or, for ECC cert: | |
297 | ``` | |
caa2e45a | 298 | acme.sh --renew -d example.com --force --ecc |
df1c9d88 | 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 | ||
59649e9b | 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 | ||
150e9c8a | 320 | # 12. Issue a cert from an existing CSR |
8371b030 | 321 | |
322 | https://github.com/Neilpang/acme.sh/wiki/Issue-a-cert-from-existing-CSR | |
323 | ||
324 | ||
2b45dba5 | 325 | # Under the Hood |
6c0ab5d2 | 326 | |
99dc89c0 | 327 | Speak ACME language using shell, directly to "Let's Encrypt". |
6c0ab5d2 N |
328 | |
329 | TODO: | |
330 | ||
2b45dba5 | 331 | # Acknowledgment |
63f04675 N |
332 | 1. Acme-tiny: https://github.com/diafygi/acme-tiny |
333 | 2. ACME protocol: https://github.com/ietf-wg-acme/acme | |
4e1f39cd | 334 | 3. Certbot: https://github.com/certbot/certbot |
63f04675 | 335 | |
150e9c8a | 336 | # License & Others |
6c0ab5d2 N |
337 | |
338 | License is GPLv3 | |
339 | ||
1d06c947 | 340 | Please Star and Fork me. |
6c0ab5d2 | 341 | |
2b45dba5 | 342 | [Issues](https://github.com/Neilpang/acme.sh/issues) and [pull requests](https://github.com/Neilpang/acme.sh/pulls) are welcomed. |
6c0ab5d2 N |
343 | |
344 | ||
fa989a55 | 345 | # Donate |
346 | 1. PayPal: donate@acme.sh | |
6c0ab5d2 | 347 | |
d4d1f0f4 | 348 | [Donate List](https://github.com/Neilpang/acme.sh/wiki/Donate-list) |
349 |