]>
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 | |
7a894c4c | 16 | #Tested OS |
daf56504 | 17 | | NO | Status| Platform| |
18 | |----|-------|---------| | |
620f8613 | 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 | |
990d46d6 | 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) |
620f8613 | 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 | |
63c6a3b0 | 32 | |14|-----| Cloud Linux https://github.com/Neilpang/le/issues/111 |
620f8613 | 33 | |15|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/openbsd.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|OpenBSD |
199067e8 | 34 | |16|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/mageia.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|Mageia |
3ad08e95 | 35 | |17|-----| OpenWRT: Tested and working. See [wiki page](https://github.com/Neilpang/acme.sh/wiki/How-to-run-on-OpenWRT) |
527dd31c | 36 | |18|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/solaris.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|SunOS/Solaris |
6c0ab5d2 | 37 | |
2b45dba5 | 38 | For all build statuses, check our [daily build project](https://github.com/Neilpang/acmetest): |
6c0ab5d2 | 39 | |
6cc11ffb | 40 | https://github.com/Neilpang/acmetest |
07f4ec4f | 41 | |
2b45dba5 SF |
42 | # Supported Mode |
43 | ||
2c75b3fd | 44 | 1. Webroot mode |
45 | 2. Standalone mode | |
46 | 3. Apache mode | |
52639149 | 47 | 4. Dns mode |
2c75b3fd | 48 | |
2b45dba5 | 49 | |
e8cce73a | 50 | |
df1c9d88 | 51 | # 1. How to install |
6c0ab5d2 | 52 | |
65938b73 | 53 | ### 1. Install online: |
6c0ab5d2 | 54 | |
5bdad844 | 55 | Check this project: https://github.com/Neilpang/get.acme.sh |
b0515cf8 | 56 | |
2b45dba5 | 57 | ```bash |
99dc89c0 | 58 | curl https://get.acme.sh | sh |
90dda23f | 59 | |
60 | ``` | |
61 | ||
62 | Or: | |
2b45dba5 SF |
63 | |
64 | ```bash | |
99dc89c0 | 65 | wget -O - https://get.acme.sh | sh |
90dda23f | 66 | |
67 | ``` | |
68 | ||
69 | ||
65938b73 | 70 | ### 2. Or, Install from git: |
2b45dba5 | 71 | |
90dda23f | 72 | Clone this project: |
2b45dba5 SF |
73 | |
74 | ```bash | |
6cc11ffb | 75 | git clone https://github.com/Neilpang/acme.sh.git |
2b45dba5 | 76 | cd ./acme.sh |
6cc11ffb | 77 | ./acme.sh --install |
6c0ab5d2 | 78 | ``` |
90dda23f | 79 | |
2b45dba5 SF |
80 | You `don't have to be root` then, although `it is recommended`. |
81 | ||
d9ded9f3 | 82 | Advanced Installation: https://github.com/Neilpang/acme.sh/wiki/How-to-install |
83 | ||
2b45dba5 | 84 | The installer will perform 3 actions: |
7a894c4c | 85 | |
2b45dba5 SF |
86 | 1. Create and copy `acme.sh` to your home dir (`$HOME`): `~/.acme.sh/`. |
87 | All certs will be placed in this folder. | |
5bdad844 | 88 | 2. Create alias for: `acme.sh=~/.acme.sh/acme.sh`. |
2b45dba5 SF |
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 | ``` | |
acc1e53a | 96 | |
2b45dba5 | 97 | After the installation, you must close current terminal and reopen again to make the alias take effect. |
acc1e53a | 98 | |
cbb5f7ec | 99 | Ok, you are ready to issue cert now. |
6c0ab5d2 | 100 | Show help message: |
2b45dba5 | 101 | |
6c0ab5d2 | 102 | ``` |
39c8f79f | 103 | |
104 | root@v1:~# acme.sh -h | |
93c9216b | 105 | |
6c0ab5d2 N |
106 | ``` |
107 | ||
df1c9d88 | 108 | # 2. Just issue a cert: |
2400e41f | 109 | |
2b45dba5 | 110 | **Example 1:** Single domain. |
2400e41f | 111 | |
2b45dba5 SF |
112 | ```bash |
113 | acme.sh --issue -d aa.com -w /home/wwwroot/aa.com | |
6c0ab5d2 | 114 | ``` |
2b45dba5 SF |
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 | |
6c0ab5d2 | 120 | ``` |
2400e41f | 121 | |
2b45dba5 | 122 | The parameter `/home/wwwroot/aa.com` is the web root folder. You **MUST** have `write access` to this folder. |
6c0ab5d2 | 123 | |
2b45dba5 SF |
124 | Second argument **"aa.com"** is the main domain you want to issue cert for. |
125 | You must have at least a domain there. | |
6c0ab5d2 | 126 | |
2b45dba5 | 127 | You must point and bind all the domains to the same webroot dir: `/home/wwwroot/aa.com`. |
6c0ab5d2 | 128 | |
2b45dba5 | 129 | Generate/issued certs will be placed in `~/.acme.sh/aa.com/` |
6c0ab5d2 | 130 | |
7a894c4c | 131 | The issued cert will be renewed every 80 days automatically. |
6c0ab5d2 | 132 | |
6cc11ffb | 133 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
a63b05a9 | 134 | |
135 | ||
150e9c8a | 136 | # 3. Install the issued cert to apache/nginx etc. |
a63b05a9 | 137 | |
150e9c8a | 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. |
2b45dba5 SF |
139 | |
140 | ```bash | |
141 | acme.sh --installcert -d aa.com \ | |
a63b05a9 | 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" | |
6c0ab5d2 | 147 | ``` |
7a894c4c | 148 | |
a63b05a9 | 149 | Only the domain is required, all the other parameters are optional. |
150 | ||
150e9c8a | 151 | Install/copy the issued cert/key to the production apache or nginx path. |
7a894c4c | 152 | |
2b45dba5 | 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`. |
6c0ab5d2 | 154 | |
df1c9d88 | 155 | # 4. Use Standalone server to issue cert |
6c0ab5d2 | 156 | |
2b45dba5 | 157 | **(requires you be root/sudoer, or you have permission to listen tcp 80 port)** |
072290f2 | 158 | |
2b45dba5 SF |
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 | |
072290f2 N |
163 | ``` |
164 | ||
6cc11ffb | 165 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
a63b05a9 | 166 | |
df1c9d88 | 167 | # 5. Use Standalone tls server to issue cert |
e22bcf7c | 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 | ||
df1c9d88 | 181 | # 6. Use Apache mode |
2b45dba5 SF |
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`. | |
a63b05a9 | 186 | |
2b45dba5 | 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. |
2c75b3fd | 188 | |
2b45dba5 | 189 | Just set string "apache" as the second argument, it will force use of apache plugin automatically. |
2c75b3fd | 190 | |
191 | ``` | |
2b45dba5 | 192 | acme.sh --issue --apache -d aa.com -d www.aa.com -d user.aa.com |
2c75b3fd | 193 | ``` |
a63b05a9 | 194 | |
6cc11ffb | 195 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
2c75b3fd | 196 | |
df1c9d88 | 197 | # 7. Use DNS mode: |
a947dbc6 | 198 | |
2b45dba5 SF |
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 | |
a947dbc6 N |
203 | ``` |
204 | ||
2b45dba5 SF |
205 | You should get the output like below: |
206 | ||
a947dbc6 N |
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 | |
a947dbc6 N |
215 | |
216 | Please add those txt records to the domains. Waiting for the dns to take effect. | |
217 | ||
a947dbc6 | 218 | ``` |
2b45dba5 SF |
219 | |
220 | Then just rerun with `renew` argument: | |
221 | ||
222 | ```bash | |
223 | acme.sh --renew -d aa.com | |
a947dbc6 N |
224 | ``` |
225 | ||
226 | Ok, it's finished. | |
227 | ||
df1c9d88 | 228 | # 8. Automatic DNS API integration |
a947dbc6 | 229 | |
2b45dba5 | 230 | If your DNS provider supports API access, we can use API to automatically issue the certs. |
6c0ab5d2 | 231 | |
2b45dba5 | 232 | You don't have do anything manually! |
ab497961 | 233 | |
2b45dba5 | 234 | ### Currently acme.sh supports: |
855d9499 | 235 | |
2b45dba5 SF |
236 | 1. Cloudflare.com API |
237 | 2. Dnspod.cn API | |
238 | 3. Cloudxns.com API | |
30de13b4 | 239 | 4. Godaddy.com API |
36246ad9 | 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 | |
2ed01ff0 | 243 | (DigitalOcean, DNSimple, DnsMadeEasy, DNSPark, EasyDNS, Namesilo, NS1, PointHQ, Rage4 and Vultr etc.) |
ab497961 | 244 | |
2b45dba5 | 245 | ##### More APIs are coming soon... |
ab497961 | 246 | |
2b45dba5 | 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. |
ab497961 | 248 | |
855d9499 | 249 | For more details: [How to use dns api](dnsapi) |
ab497961 | 250 | |
df1c9d88 | 251 | # 9. Issue ECC certificate: |
2b45dba5 SF |
252 | |
253 | `Let's Encrypt` now can issue **ECDSA** certificates. | |
254 | ||
1add47a6 | 255 | And we also support it. |
256 | ||
8b92aab7 | 257 | Just set the `length` parameter with a prefix `ec-`. |
2b45dba5 | 258 | |
1add47a6 | 259 | For example: |
9e6c4208 | 260 | |
2b45dba5 | 261 | ### Single domain ECC cerfiticate: |
9e6c4208 | 262 | |
2b45dba5 SF |
263 | ```bash |
264 | acme.sh --issue -w /home/wwwroot/aa.com -d aa.com --keylength ec-256 | |
1add47a6 | 265 | ``` |
2b45dba5 SF |
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 | |
9e6c4208 N |
271 | ``` |
272 | ||
1add47a6 | 273 | Please look at the last parameter above. |
274 | ||
275 | Valid values are: | |
276 | ||
2b45dba5 SF |
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.)** | |
1add47a6 | 280 | |
df1c9d88 | 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 | ||
59649e9b | 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 | ||
150e9c8a | 316 | # 12. Issue a cert from an existing CSR |
8371b030 | 317 | |
318 | https://github.com/Neilpang/acme.sh/wiki/Issue-a-cert-from-existing-CSR | |
319 | ||
320 | ||
2b45dba5 | 321 | # Under the Hood |
6c0ab5d2 | 322 | |
99dc89c0 | 323 | Speak ACME language using shell, directly to "Let's Encrypt". |
6c0ab5d2 N |
324 | |
325 | TODO: | |
326 | ||
2b45dba5 | 327 | # Acknowledgment |
63f04675 N |
328 | 1. Acme-tiny: https://github.com/diafygi/acme-tiny |
329 | 2. ACME protocol: https://github.com/ietf-wg-acme/acme | |
4e1f39cd | 330 | 3. Certbot: https://github.com/certbot/certbot |
63f04675 | 331 | |
150e9c8a | 332 | # License & Others |
6c0ab5d2 N |
333 | |
334 | License is GPLv3 | |
335 | ||
1d06c947 | 336 | Please Star and Fork me. |
6c0ab5d2 | 337 | |
2b45dba5 | 338 | [Issues](https://github.com/Neilpang/acme.sh/issues) and [pull requests](https://github.com/Neilpang/acme.sh/pulls) are welcomed. |
6c0ab5d2 N |
339 | |
340 | ||
fa989a55 | 341 | # Donate |
342 | 1. PayPal: donate@acme.sh | |
6c0ab5d2 | 343 | |
d4d1f0f4 | 344 | [Donate List](https://github.com/Neilpang/acme.sh/wiki/Donate-list) |
345 |