]>
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) |
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, curl. https://github.com/Neilpang/le/issues/94) | |
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 | |
106 | v2.1.0 | |
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. | |
6cc11ffb | 150 | --home Specifies the home dir for acme.sh |
6c0ab5d2 N |
151 | ``` |
152 | ||
153 | # Just issue a cert: | |
2400e41f | 154 | |
2b45dba5 | 155 | **Example 1:** Single domain. |
2400e41f | 156 | |
2b45dba5 SF |
157 | ```bash |
158 | acme.sh --issue -d aa.com -w /home/wwwroot/aa.com | |
6c0ab5d2 | 159 | ``` |
2b45dba5 SF |
160 | |
161 | **Example 2:** Multiple domains in the same cert. | |
162 | ||
163 | ```bash | |
164 | acme.sh --issue -d aa.com -d www.aa.com -d cp.aa.com -w /home/wwwroot/aa.com | |
6c0ab5d2 | 165 | ``` |
2400e41f | 166 | |
2b45dba5 | 167 | The parameter `/home/wwwroot/aa.com` is the web root folder. You **MUST** have `write access` to this folder. |
6c0ab5d2 | 168 | |
2b45dba5 SF |
169 | Second argument **"aa.com"** is the main domain you want to issue cert for. |
170 | You must have at least a domain there. | |
6c0ab5d2 | 171 | |
2b45dba5 | 172 | You must point and bind all the domains to the same webroot dir: `/home/wwwroot/aa.com`. |
6c0ab5d2 | 173 | |
2b45dba5 | 174 | Generate/issued certs will be placed in `~/.acme.sh/aa.com/` |
6c0ab5d2 | 175 | |
7a894c4c | 176 | The issued cert will be renewed every 80 days automatically. |
6c0ab5d2 | 177 | |
6cc11ffb | 178 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
a63b05a9 | 179 | |
180 | ||
7a894c4c | 181 | # Install issued cert to apache/nginx etc. |
a63b05a9 | 182 | |
2b45dba5 SF |
183 | After you issue a cert, you probably want to install the cert with your nginx/apache or other servers you may be using. |
184 | ||
185 | ```bash | |
186 | acme.sh --installcert -d aa.com \ | |
a63b05a9 | 187 | --certpath /path/to/certfile/in/apache/nginx \ |
188 | --keypath /path/to/keyfile/in/apache/nginx \ | |
189 | --capath /path/to/ca/certfile/apache/nginx \ | |
190 | --fullchainpath path/to/fullchain/certfile/apache/nginx \ | |
191 | --reloadcmd "service apache2|nginx reload" | |
6c0ab5d2 | 192 | ``` |
7a894c4c | 193 | |
a63b05a9 | 194 | Only the domain is required, all the other parameters are optional. |
195 | ||
7a894c4c N |
196 | Install the issued cert/key to the production apache or nginx path. |
197 | ||
2b45dba5 | 198 | 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 | 199 | |
2b45dba5 | 200 | # Use Standalone server to issue cert |
6c0ab5d2 | 201 | |
2b45dba5 | 202 | **(requires you be root/sudoer, or you have permission to listen tcp 80 port)** |
072290f2 | 203 | |
2b45dba5 SF |
204 | Same usage as above, just give `no` as `--webroot` or `-w`. |
205 | ||
206 | The tcp `80` port **MUST** be free to listen, otherwise you will be prompted to free the `80` port and try again. | |
207 | ||
208 | ```bash | |
209 | acme.sh --issue --standalone -d aa.com -d www.aa.com -d cp.aa.com | |
072290f2 N |
210 | ``` |
211 | ||
6cc11ffb | 212 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
a63b05a9 | 213 | |
2b45dba5 SF |
214 | # Use Apache mode |
215 | ||
216 | **(requires you be root/sudoer, since it is required to interact with apache server)** | |
217 | ||
218 | If you are running a web server, apache or nginx, it is recommended to use the `Webroot mode`. | |
a63b05a9 | 219 | |
2b45dba5 | 220 | 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 | 221 | |
2b45dba5 | 222 | Just set string "apache" as the second argument, it will force use of apache plugin automatically. |
2c75b3fd | 223 | |
224 | ``` | |
2b45dba5 | 225 | acme.sh --issue --apache -d aa.com -d www.aa.com -d user.aa.com |
2c75b3fd | 226 | ``` |
a63b05a9 | 227 | |
6cc11ffb | 228 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
2c75b3fd | 229 | |
a947dbc6 | 230 | # Use DNS mode: |
a947dbc6 | 231 | |
2b45dba5 SF |
232 | Support the `dns-01` challenge. |
233 | ||
234 | ```bash | |
235 | acme.sh --issue --dns -d aa.com -d www.aa.com -d user.aa.com | |
a947dbc6 N |
236 | ``` |
237 | ||
2b45dba5 SF |
238 | You should get the output like below: |
239 | ||
a947dbc6 N |
240 | ``` |
241 | Add the following txt record: | |
242 | Domain:_acme-challenge.aa.com | |
243 | Txt value:9ihDbjYfTExAYeDs4DBUeuTo18KBzwvTEjUnSwd32-c | |
244 | ||
245 | Add the following txt record: | |
246 | Domain:_acme-challenge.www.aa.com | |
247 | Txt value:9ihDbjxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
a947dbc6 N |
248 | |
249 | Please add those txt records to the domains. Waiting for the dns to take effect. | |
250 | ||
a947dbc6 | 251 | ``` |
2b45dba5 SF |
252 | |
253 | Then just rerun with `renew` argument: | |
254 | ||
255 | ```bash | |
256 | acme.sh --renew -d aa.com | |
a947dbc6 N |
257 | ``` |
258 | ||
259 | Ok, it's finished. | |
260 | ||
2b45dba5 | 261 | # Automatic DNS API integration |
a947dbc6 | 262 | |
2b45dba5 | 263 | If your DNS provider supports API access, we can use API to automatically issue the certs. |
6c0ab5d2 | 264 | |
2b45dba5 | 265 | You don't have do anything manually! |
ab497961 | 266 | |
2b45dba5 | 267 | ### Currently acme.sh supports: |
855d9499 | 268 | |
2b45dba5 SF |
269 | 1. Cloudflare.com API |
270 | 2. Dnspod.cn API | |
271 | 3. Cloudxns.com API | |
6cc11ffb | 272 | 4. AWS Route 53, see: https://github.com/Neilpang/acme.sh/issues/65 |
ab497961 | 273 | |
2b45dba5 | 274 | ##### More APIs are coming soon... |
ab497961 | 275 | |
2b45dba5 | 276 | 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 | 277 | |
855d9499 | 278 | For more details: [How to use dns api](dnsapi) |
ab497961 | 279 | |
1add47a6 | 280 | # Issue ECC certificate: |
2b45dba5 SF |
281 | |
282 | `Let's Encrypt` now can issue **ECDSA** certificates. | |
283 | ||
1add47a6 | 284 | And we also support it. |
285 | ||
8b92aab7 | 286 | Just set the `length` parameter with a prefix `ec-`. |
2b45dba5 | 287 | |
1add47a6 | 288 | For example: |
9e6c4208 | 289 | |
2b45dba5 | 290 | ### Single domain ECC cerfiticate: |
9e6c4208 | 291 | |
2b45dba5 SF |
292 | ```bash |
293 | acme.sh --issue -w /home/wwwroot/aa.com -d aa.com --keylength ec-256 | |
1add47a6 | 294 | ``` |
2b45dba5 SF |
295 | |
296 | SAN multi domain ECC certificate: | |
297 | ||
298 | ```bash | |
299 | acme.sh --issue -w /home/wwwroot/aa.com -d aa.com -d www.aa.com --keylength ec-256 | |
9e6c4208 N |
300 | ``` |
301 | ||
1add47a6 | 302 | Please look at the last parameter above. |
303 | ||
304 | Valid values are: | |
305 | ||
2b45dba5 SF |
306 | 1. **ec-256 (prime256v1, "ECDSA P-256")** |
307 | 2. **ec-384 (secp384r1, "ECDSA P-384")** | |
308 | 3. **ec-521 (secp521r1, "ECDSA P-521", which is not supported by Let's Encrypt yet.)** | |
1add47a6 | 309 | |
2b45dba5 | 310 | # Under the Hood |
6c0ab5d2 | 311 | |
2b45dba5 | 312 | Speak ACME language using bash, directly to "Let's Encrypt". |
6c0ab5d2 N |
313 | |
314 | TODO: | |
315 | ||
2b45dba5 | 316 | # Acknowledgment |
63f04675 N |
317 | 1. Acme-tiny: https://github.com/diafygi/acme-tiny |
318 | 2. ACME protocol: https://github.com/ietf-wg-acme/acme | |
319 | 3. letsencrypt: https://github.com/letsencrypt/letsencrypt | |
320 | ||
2b45dba5 | 321 | # License & Other |
6c0ab5d2 N |
322 | |
323 | License is GPLv3 | |
324 | ||
1d06c947 | 325 | Please Star and Fork me. |
6c0ab5d2 | 326 | |
2b45dba5 | 327 | [Issues](https://github.com/Neilpang/acme.sh/issues) and [pull requests](https://github.com/Neilpang/acme.sh/pulls) are welcomed. |
6c0ab5d2 N |
328 | |
329 | ||
330 |