]>
Commit | Line | Data |
---|---|---|
2b45dba5 SF |
1 | # An ACME Shell script: acme.sh |
2 | - An ACME protocol client written purely in Bash (Unix shell) language. | |
3 | - Fully ACME protocol implementation. | |
4 | - Simple, powerful and very easy to use. You only need 3 minutes to learn. | |
8b92aab7 | 5 | |
2b45dba5 SF |
6 | - Simplest shell script for Let's Encrypt free certificate client. |
7 | - Purely written in Bash with no dependencies on python or Let's Encrypt official client. | |
8 | - Just one script, to issue, renew and install your certificates automatically. | |
6c0ab5d2 | 9 | |
2b45dba5 | 10 | It's probably the `easiest&smallest&smartest` shell script to automatically issue & renew the free certificates from Let's Encrypt. |
6c0ab5d2 | 11 | |
2b45dba5 | 12 | DOES NOT require `root/sudoer` access. |
6c0ab5d2 | 13 | |
6cc11ffb | 14 | Wiki: https://github.com/Neilpang/acme.sh/wiki |
de9fd54e | 15 | |
7a894c4c | 16 | #Tested OS |
04eb75a1 | 17 | 1. Ubuntu [![](https://cdn.rawgit.com/Neilpang/letest/master/status/ubuntu-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status) |
18 | 2. Debian [![](https://cdn.rawgit.com/Neilpang/letest/master/status/debian-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status) | |
19 | 3. CentOS [![](https://cdn.rawgit.com/Neilpang/letest/master/status/centos-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status) | |
779e7ea0 | 20 | 4. Windows (cygwin with curl, openssl and crontab included) [![](https://cdn.rawgit.com/Neilpang/letest/master/status/windows.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status) |
21 | 5. FreeBSD with bash [![](https://cdn.rawgit.com/Neilpang/letest/master/status/freebsd.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status) | |
387c2eab | 22 | 6. pfsense with bash and curl |
04eb75a1 | 23 | 7. openSUSE [![](https://cdn.rawgit.com/Neilpang/letest/master/status/opensuse-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status) |
937cbf6d | 24 | 8. Alpine Linux [![](https://cdn.rawgit.com/Neilpang/letest/master/status/alpine-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status) (with bash and curl) |
2f06c850 | 25 | 9. Archlinux [![](https://cdn.rawgit.com/Neilpang/letest/master/status/base-archlinux.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status) |
04eb75a1 | 26 | 10. fedora [![](https://cdn.rawgit.com/Neilpang/letest/master/status/fedora-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status) |
d3d884c1 | 27 | 11. Kali Linux [![](https://cdn.rawgit.com/Neilpang/letest/master/status/kalilinux-kali-linux-docker.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status) |
a34bd89f | 28 | 12. Oracle Linux [![](https://cdn.rawgit.com/Neilpang/letest/master/status/oraclelinux-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status) |
ddc04a75 | 29 | 13. Cloud Linux https://github.com/Neilpang/le/issues/111 |
b7604c06 | 30 | 14. Proxmox https://pve.proxmox.com/wiki/HTTPSCertificateConfiguration#Let.27s_Encrypt_using_le.sh |
31 | ||
6c0ab5d2 | 32 | |
2b45dba5 | 33 | For all build statuses, check our [daily build project](https://github.com/Neilpang/acmetest): |
6c0ab5d2 | 34 | |
6cc11ffb | 35 | https://github.com/Neilpang/acmetest |
07f4ec4f | 36 | |
2b45dba5 SF |
37 | # Supported Mode |
38 | ||
2c75b3fd | 39 | 1. Webroot mode |
40 | 2. Standalone mode | |
41 | 3. Apache mode | |
52639149 | 42 | 4. Dns mode |
2c75b3fd | 43 | |
6cc11ffb | 44 | # Upgrade from 1.x to 2.x |
2b45dba5 | 45 | |
e8cce73a | 46 | You can simply uninstall 1.x and re-install 2.x. |
2b45dba5 | 47 | 2.x is 100% compatible to 1.x. You will feel right at home as if nothing has changed. |
e8cce73a | 48 | |
6cc11ffb | 49 | # le.sh renamed to acme.sh NOW! |
6cc11ffb | 50 | |
2b45dba5 SF |
51 | All configurations are 100% compatible between `le.sh` and `acme.sh`. You just need to uninstall `le.sh` and re-install `acme.sh` again. |
52 | Nothing will be broken during the process. | |
53 | ||
54 | # How to install | |
6c0ab5d2 | 55 | |
65938b73 | 56 | ### 1. Install online: |
6c0ab5d2 | 57 | |
b0515cf8 | 58 | Check this project:https://github.com/Neilpang/get.acme.sh |
59 | ||
2b45dba5 | 60 | ```bash |
b0515cf8 | 61 | curl https://get.acme.sh | bash |
90dda23f | 62 | |
63 | ``` | |
64 | ||
65 | Or: | |
2b45dba5 SF |
66 | |
67 | ```bash | |
b0515cf8 | 68 | wget -O - https://get.acme.sh | bash |
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 | ||
85 | The installer will perform 3 actions: | |
7a894c4c | 86 | |
2b45dba5 SF |
87 | 1. Create and copy `acme.sh` to your home dir (`$HOME`): `~/.acme.sh/`. |
88 | All certs will be placed in this folder. | |
89 | 2. Create alia for: `acme.sh=~/.acme.sh/acme.sh`. | |
90 | 3. Create everyday cron job to check and renew the cert if needed. | |
91 | ||
92 | Cron entry example: | |
93 | ||
94 | ```bash | |
95 | 0 0 * * * "/home/user/.acme.sh"/acme.sh --cron --home "/home/user/.acme.sh" > /dev/null | |
96 | ``` | |
acc1e53a | 97 | |
2b45dba5 | 98 | After the installation, you must close current terminal and reopen again to make the alias take effect. |
acc1e53a | 99 | |
cbb5f7ec | 100 | Ok, you are ready to issue cert now. |
6c0ab5d2 | 101 | Show help message: |
2b45dba5 | 102 | |
6c0ab5d2 | 103 | ``` |
6cc11ffb | 104 | root@v1:~# acme.sh |
105 | https://github.com/Neilpang/acme.sh | |
93c9216b | 106 | v2.1.1 |
6cc11ffb | 107 | Usage: acme.sh command ...[parameters].... |
a63b05a9 | 108 | Commands: |
109 | --help, -h Show this help message. | |
110 | --version, -v Show version info. | |
6cc11ffb | 111 | --install Install acme.sh to your system. |
112 | --uninstall Uninstall acme.sh, and uninstall the cron job. | |
a63b05a9 | 113 | --issue Issue a cert. |
114 | --installcert Install the issued cert to apache/nginx or any other server. | |
115 | --renew, -r Renew a cert. | |
116 | --renewAll Renew all the certs | |
117 | --revoke Revoke a cert. | |
118 | --installcronjob Install the cron job to renew certs, you don't need to call this. The 'install' command can automatically install the cron job. | |
119 | --uninstallcronjob Uninstall the cron job. The 'uninstall' command can do this automatically. | |
120 | --cron Run cron job to renew all the certs. | |
121 | --toPkcs Export the certificate and key to a pfx file. | |
122 | --createAccountKey, -cak Create an account private key, professional use. | |
123 | --createDomainKey, -cdk Create an domain private key, professional use. | |
124 | --createCSR, -ccsr Create CSR , professional use. | |
125 | ||
126 | Parameters: | |
127 | --domain, -d domain.tld Specifies a domain, used to issue, renew or revoke etc. | |
128 | --force, -f Used to force to install or force to renew a cert immediately. | |
129 | --staging, --test Use staging server, just for test. | |
130 | --debug Output debug info. | |
131 | ||
132 | --webroot, -w /path/to/webroot Specifies the web root folder for web root mode. | |
133 | --standalone Use standalone mode. | |
134 | --apache Use apache mode. | |
135 | --dns [dns-cf|dns-dp|dns-cx|/path/to/api/file] Use dns mode or dns api. | |
136 | ||
137 | --keylength, -k [2048] Specifies the domain key length: 2048, 3072, 4096, 8192 or ec-256, ec-384. | |
138 | --accountkeylength, -ak [2048] Specifies the account key length. | |
139 | ||
140 | These parameters are to install the cert to nginx/apache or anyother server after issue/renew a cert: | |
141 | ||
142 | --certpath /path/to/real/cert/file After issue/renew, the cert will be copied to this path. | |
143 | --keypath /path/to/real/key/file After issue/renew, the key will be copied to this path. | |
144 | --capath /path/to/real/ca/file After issue/renew, the intermediate cert will be copied to this path. | |
145 | --fullchainpath /path/to/fullchain/file After issue/renew, the fullchain cert will be copied to this path. | |
146 | ||
147 | --reloadcmd "service nginx reload" After issue/renew, it's used to reload the server. | |
148 | ||
149 | --accountconf Specifies a customized account config file. | |
93c9216b | 150 | --home Specifies the home dir for acme.sh . |
151 | --useragent Specifies the user agent string. it will be saved for future use too. | |
b5eb4b90 | 152 | --accountemail Specifies the account email for registering, Only valid for the '--install' command. |
153 | --accountkey Specifyes the account key path, Only valid for the '--install' command. | |
93c9216b | 154 | |
6c0ab5d2 N |
155 | ``` |
156 | ||
157 | # Just issue a cert: | |
2400e41f | 158 | |
2b45dba5 | 159 | **Example 1:** Single domain. |
2400e41f | 160 | |
2b45dba5 SF |
161 | ```bash |
162 | acme.sh --issue -d aa.com -w /home/wwwroot/aa.com | |
6c0ab5d2 | 163 | ``` |
2b45dba5 SF |
164 | |
165 | **Example 2:** Multiple domains in the same cert. | |
166 | ||
167 | ```bash | |
168 | acme.sh --issue -d aa.com -d www.aa.com -d cp.aa.com -w /home/wwwroot/aa.com | |
6c0ab5d2 | 169 | ``` |
2400e41f | 170 | |
2b45dba5 | 171 | The parameter `/home/wwwroot/aa.com` is the web root folder. You **MUST** have `write access` to this folder. |
6c0ab5d2 | 172 | |
2b45dba5 SF |
173 | Second argument **"aa.com"** is the main domain you want to issue cert for. |
174 | You must have at least a domain there. | |
6c0ab5d2 | 175 | |
2b45dba5 | 176 | You must point and bind all the domains to the same webroot dir: `/home/wwwroot/aa.com`. |
6c0ab5d2 | 177 | |
2b45dba5 | 178 | Generate/issued certs will be placed in `~/.acme.sh/aa.com/` |
6c0ab5d2 | 179 | |
7a894c4c | 180 | The issued cert will be renewed every 80 days automatically. |
6c0ab5d2 | 181 | |
6cc11ffb | 182 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
a63b05a9 | 183 | |
184 | ||
7a894c4c | 185 | # Install issued cert to apache/nginx etc. |
a63b05a9 | 186 | |
2b45dba5 SF |
187 | After you issue a cert, you probably want to install the cert with your nginx/apache or other servers you may be using. |
188 | ||
189 | ```bash | |
190 | acme.sh --installcert -d aa.com \ | |
a63b05a9 | 191 | --certpath /path/to/certfile/in/apache/nginx \ |
192 | --keypath /path/to/keyfile/in/apache/nginx \ | |
193 | --capath /path/to/ca/certfile/apache/nginx \ | |
194 | --fullchainpath path/to/fullchain/certfile/apache/nginx \ | |
195 | --reloadcmd "service apache2|nginx reload" | |
6c0ab5d2 | 196 | ``` |
7a894c4c | 197 | |
a63b05a9 | 198 | Only the domain is required, all the other parameters are optional. |
199 | ||
7a894c4c N |
200 | Install the issued cert/key to the production apache or nginx path. |
201 | ||
2b45dba5 | 202 | 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 | 203 | |
2b45dba5 | 204 | # Use Standalone server to issue cert |
6c0ab5d2 | 205 | |
2b45dba5 | 206 | **(requires you be root/sudoer, or you have permission to listen tcp 80 port)** |
072290f2 | 207 | |
2b45dba5 SF |
208 | Same usage as above, just give `no` as `--webroot` or `-w`. |
209 | ||
210 | The tcp `80` port **MUST** be free to listen, otherwise you will be prompted to free the `80` port and try again. | |
211 | ||
212 | ```bash | |
213 | acme.sh --issue --standalone -d aa.com -d www.aa.com -d cp.aa.com | |
072290f2 N |
214 | ``` |
215 | ||
6cc11ffb | 216 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
a63b05a9 | 217 | |
2b45dba5 SF |
218 | # Use Apache mode |
219 | ||
220 | **(requires you be root/sudoer, since it is required to interact with apache server)** | |
221 | ||
222 | If you are running a web server, apache or nginx, it is recommended to use the `Webroot mode`. | |
a63b05a9 | 223 | |
2b45dba5 | 224 | 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 | 225 | |
2b45dba5 | 226 | Just set string "apache" as the second argument, it will force use of apache plugin automatically. |
2c75b3fd | 227 | |
228 | ``` | |
2b45dba5 | 229 | acme.sh --issue --apache -d aa.com -d www.aa.com -d user.aa.com |
2c75b3fd | 230 | ``` |
a63b05a9 | 231 | |
6cc11ffb | 232 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
2c75b3fd | 233 | |
a947dbc6 | 234 | # Use DNS mode: |
a947dbc6 | 235 | |
2b45dba5 SF |
236 | Support the `dns-01` challenge. |
237 | ||
238 | ```bash | |
239 | acme.sh --issue --dns -d aa.com -d www.aa.com -d user.aa.com | |
a947dbc6 N |
240 | ``` |
241 | ||
2b45dba5 SF |
242 | You should get the output like below: |
243 | ||
a947dbc6 N |
244 | ``` |
245 | Add the following txt record: | |
246 | Domain:_acme-challenge.aa.com | |
247 | Txt value:9ihDbjYfTExAYeDs4DBUeuTo18KBzwvTEjUnSwd32-c | |
248 | ||
249 | Add the following txt record: | |
250 | Domain:_acme-challenge.www.aa.com | |
251 | Txt value:9ihDbjxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
a947dbc6 N |
252 | |
253 | Please add those txt records to the domains. Waiting for the dns to take effect. | |
254 | ||
a947dbc6 | 255 | ``` |
2b45dba5 SF |
256 | |
257 | Then just rerun with `renew` argument: | |
258 | ||
259 | ```bash | |
260 | acme.sh --renew -d aa.com | |
a947dbc6 N |
261 | ``` |
262 | ||
263 | Ok, it's finished. | |
264 | ||
2b45dba5 | 265 | # Automatic DNS API integration |
a947dbc6 | 266 | |
2b45dba5 | 267 | If your DNS provider supports API access, we can use API to automatically issue the certs. |
6c0ab5d2 | 268 | |
2b45dba5 | 269 | You don't have do anything manually! |
ab497961 | 270 | |
2b45dba5 | 271 | ### Currently acme.sh supports: |
855d9499 | 272 | |
2b45dba5 SF |
273 | 1. Cloudflare.com API |
274 | 2. Dnspod.cn API | |
275 | 3. Cloudxns.com API | |
6cc11ffb | 276 | 4. AWS Route 53, see: https://github.com/Neilpang/acme.sh/issues/65 |
ab497961 | 277 | |
2b45dba5 | 278 | ##### More APIs are coming soon... |
ab497961 | 279 | |
2b45dba5 | 280 | 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 | 281 | |
855d9499 | 282 | For more details: [How to use dns api](dnsapi) |
ab497961 | 283 | |
1add47a6 | 284 | # Issue ECC certificate: |
2b45dba5 SF |
285 | |
286 | `Let's Encrypt` now can issue **ECDSA** certificates. | |
287 | ||
1add47a6 | 288 | And we also support it. |
289 | ||
8b92aab7 | 290 | Just set the `length` parameter with a prefix `ec-`. |
2b45dba5 | 291 | |
1add47a6 | 292 | For example: |
9e6c4208 | 293 | |
2b45dba5 | 294 | ### Single domain ECC cerfiticate: |
9e6c4208 | 295 | |
2b45dba5 SF |
296 | ```bash |
297 | acme.sh --issue -w /home/wwwroot/aa.com -d aa.com --keylength ec-256 | |
1add47a6 | 298 | ``` |
2b45dba5 SF |
299 | |
300 | SAN multi domain ECC certificate: | |
301 | ||
302 | ```bash | |
303 | acme.sh --issue -w /home/wwwroot/aa.com -d aa.com -d www.aa.com --keylength ec-256 | |
9e6c4208 N |
304 | ``` |
305 | ||
1add47a6 | 306 | Please look at the last parameter above. |
307 | ||
308 | Valid values are: | |
309 | ||
2b45dba5 SF |
310 | 1. **ec-256 (prime256v1, "ECDSA P-256")** |
311 | 2. **ec-384 (secp384r1, "ECDSA P-384")** | |
312 | 3. **ec-521 (secp521r1, "ECDSA P-521", which is not supported by Let's Encrypt yet.)** | |
1add47a6 | 313 | |
2b45dba5 | 314 | # Under the Hood |
6c0ab5d2 | 315 | |
2b45dba5 | 316 | Speak ACME language using bash, directly to "Let's Encrypt". |
6c0ab5d2 N |
317 | |
318 | TODO: | |
319 | ||
2b45dba5 | 320 | # Acknowledgment |
63f04675 N |
321 | 1. Acme-tiny: https://github.com/diafygi/acme-tiny |
322 | 2. ACME protocol: https://github.com/ietf-wg-acme/acme | |
323 | 3. letsencrypt: https://github.com/letsencrypt/letsencrypt | |
324 | ||
2b45dba5 | 325 | # License & Other |
6c0ab5d2 N |
326 | |
327 | License is GPLv3 | |
328 | ||
1d06c947 | 329 | Please Star and Fork me. |
6c0ab5d2 | 330 | |
2b45dba5 | 331 | [Issues](https://github.com/Neilpang/acme.sh/issues) and [pull requests](https://github.com/Neilpang/acme.sh/pulls) are welcomed. |
6c0ab5d2 N |
332 | |
333 | ||
334 |