]>
Commit | Line | Data |
---|---|---|
6cc11ffb | 1 | # A acme Shell script: acme.sh |
2 | A acme protocol client in pure bash language. | |
3 | Fully ACME protocol implementation. | |
4 | Simple, Powerful and very easy to use, you only need 3 minutes to learn. | |
8b92aab7 | 5 | |
6cc11ffb | 6 | Simplest shell script for LetsEncrypt free Certificate client |
7 | Pure written in bash, no dependencies to python or LetsEncrypt official client. | |
d8069cd4 | 8 | Just one script, to issue, renew your certificates automatically. |
6c0ab5d2 | 9 | |
cbb5f7ec | 10 | Probably it's the smallest&easiest&smartest shell script to automatically issue & renew the free certificates from LetsEncrypt. |
6c0ab5d2 | 11 | |
90dda23f | 12 | NOT require to be `root/sudoer`. |
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 | |
387c2eab | 33 | For all the build status, check our daily build project: |
6c0ab5d2 | 34 | |
6cc11ffb | 35 | https://github.com/Neilpang/acmetest |
07f4ec4f | 36 | |
2c75b3fd | 37 | #Supported Mode |
38 | 1. Webroot mode | |
39 | 2. Standalone mode | |
40 | 3. Apache mode | |
52639149 | 41 | 4. Dns mode |
2c75b3fd | 42 | |
6cc11ffb | 43 | # Upgrade from 1.x to 2.x |
e8cce73a | 44 | You can simply uninstall 1.x and re-install 2.x. |
45 | 2.x is 100% compatible to 1.x. You will feel nothing changed. | |
46 | ||
6cc11ffb | 47 | # le.sh renamed to acme.sh NOW! |
48 | All configurations are 100% compatible. You just need to uninstall `le.sh` and re-install `acme.sh` again. | |
49 | Nothing broken. | |
50 | ||
90dda23f | 51 | #How to install |
6c0ab5d2 | 52 | |
65938b73 | 53 | ### 1. Install online: |
6c0ab5d2 | 54 | |
6c0ab5d2 | 55 | ``` |
6cc11ffb | 56 | curl https://raw.githubusercontent.com/Neilpang/acme.sh/master/acme.sh | INSTALLONLINE=1 bash |
90dda23f | 57 | |
58 | ``` | |
59 | ||
60 | Or: | |
61 | ``` | |
6cc11ffb | 62 | wget -O - https://raw.githubusercontent.com/Neilpang/acme.sh/master/acme.sh | INSTALLONLINE=1 bash |
90dda23f | 63 | |
64 | ``` | |
65 | ||
66 | ||
65938b73 | 67 | ### 2. Or, Install from git: |
90dda23f | 68 | Clone this project: |
69 | ``` | |
6cc11ffb | 70 | git clone https://github.com/Neilpang/acme.sh.git |
71 | cd acme.sh | |
72 | ./acme.sh --install | |
6c0ab5d2 | 73 | ``` |
90dda23f | 74 | |
d0064bc3 | 75 | You don't have to be root then, although it is recommended. |
7a894c4c | 76 | |
db25a3ea | 77 | Which does 3 jobs: |
6cc11ffb | 78 | * create and copy `acme.sh` to your home dir: `~/.acme.sh/` |
6c0ab5d2 | 79 | All the certs will be placed in this folder. |
6cc11ffb | 80 | * create alias : `acme.sh=~/.acme.sh/acme.sh`. |
db25a3ea | 81 | * create everyday cron job to check and renew the cert if needed. |
acc1e53a | 82 | |
9b292d58 | 83 | After install, you must close current terminal and reopen again to make the alias take effect. |
acc1e53a | 84 | |
cbb5f7ec | 85 | Ok, you are ready to issue cert now. |
6c0ab5d2 N |
86 | Show help message: |
87 | ``` | |
6cc11ffb | 88 | root@v1:~# acme.sh |
89 | https://github.com/Neilpang/acme.sh | |
90 | v2.1.0 | |
91 | Usage: acme.sh command ...[parameters].... | |
a63b05a9 | 92 | Commands: |
93 | --help, -h Show this help message. | |
94 | --version, -v Show version info. | |
6cc11ffb | 95 | --install Install acme.sh to your system. |
96 | --uninstall Uninstall acme.sh, and uninstall the cron job. | |
a63b05a9 | 97 | --issue Issue a cert. |
98 | --installcert Install the issued cert to apache/nginx or any other server. | |
99 | --renew, -r Renew a cert. | |
100 | --renewAll Renew all the certs | |
101 | --revoke Revoke a cert. | |
102 | --installcronjob Install the cron job to renew certs, you don't need to call this. The 'install' command can automatically install the cron job. | |
103 | --uninstallcronjob Uninstall the cron job. The 'uninstall' command can do this automatically. | |
104 | --cron Run cron job to renew all the certs. | |
105 | --toPkcs Export the certificate and key to a pfx file. | |
106 | --createAccountKey, -cak Create an account private key, professional use. | |
107 | --createDomainKey, -cdk Create an domain private key, professional use. | |
108 | --createCSR, -ccsr Create CSR , professional use. | |
109 | ||
110 | Parameters: | |
111 | --domain, -d domain.tld Specifies a domain, used to issue, renew or revoke etc. | |
112 | --force, -f Used to force to install or force to renew a cert immediately. | |
113 | --staging, --test Use staging server, just for test. | |
114 | --debug Output debug info. | |
115 | ||
116 | --webroot, -w /path/to/webroot Specifies the web root folder for web root mode. | |
117 | --standalone Use standalone mode. | |
118 | --apache Use apache mode. | |
119 | --dns [dns-cf|dns-dp|dns-cx|/path/to/api/file] Use dns mode or dns api. | |
120 | ||
121 | --keylength, -k [2048] Specifies the domain key length: 2048, 3072, 4096, 8192 or ec-256, ec-384. | |
122 | --accountkeylength, -ak [2048] Specifies the account key length. | |
123 | ||
124 | These parameters are to install the cert to nginx/apache or anyother server after issue/renew a cert: | |
125 | ||
126 | --certpath /path/to/real/cert/file After issue/renew, the cert will be copied to this path. | |
127 | --keypath /path/to/real/key/file After issue/renew, the key will be copied to this path. | |
128 | --capath /path/to/real/ca/file After issue/renew, the intermediate cert will be copied to this path. | |
129 | --fullchainpath /path/to/fullchain/file After issue/renew, the fullchain cert will be copied to this path. | |
130 | ||
131 | --reloadcmd "service nginx reload" After issue/renew, it's used to reload the server. | |
132 | ||
133 | --accountconf Specifies a customized account config file. | |
6cc11ffb | 134 | --home Specifies the home dir for acme.sh |
65938b73 | 135 | |
6c0ab5d2 | 136 | |
6c0ab5d2 N |
137 | |
138 | ``` | |
139 | ||
140 | # Just issue a cert: | |
2400e41f N |
141 | Example 1: |
142 | Only one domain: | |
143 | ``` | |
6cc11ffb | 144 | acme.sh --issue -d aa.com -w /home/wwwroot/aa.com |
2400e41f N |
145 | ``` |
146 | ||
147 | Example 2: | |
148 | Multiple domains in the same cert: | |
149 | ||
6c0ab5d2 | 150 | ``` |
6cc11ffb | 151 | acme.sh --issue -d aa.com -d www.aa.com -d cp.aa.com -w /home/wwwroot/aa.com |
6c0ab5d2 | 152 | ``` |
2400e41f | 153 | |
a63b05a9 | 154 | The parameter `/home/wwwroot/aa.com` is the web root folder, You must have `write` access to this folder. |
6c0ab5d2 | 155 | |
d337abca | 156 | Second argument "aa.com" is the main domain you want to issue cert for. |
a63b05a9 | 157 | You must have at least domain there. |
6c0ab5d2 | 158 | |
d337abca | 159 | You must point and bind all the domains to the same webroot dir:`/home/wwwroot/aa.com` |
6c0ab5d2 | 160 | |
6cc11ffb | 161 | The cert will be placed in `~/.acme.sh/aa.com/` |
6c0ab5d2 | 162 | |
7a894c4c | 163 | The issued cert will be renewed every 80 days automatically. |
6c0ab5d2 | 164 | |
a63b05a9 | 165 | |
6cc11ffb | 166 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
a63b05a9 | 167 | |
168 | ||
7a894c4c | 169 | # Install issued cert to apache/nginx etc. |
e8cce73a | 170 | After you issue a cert, you probably want to install the cert to your nginx/apache or other servers to use. |
a63b05a9 | 171 | |
6c0ab5d2 | 172 | ``` |
6cc11ffb | 173 | acme.sh --installcert -d aa.com \ |
a63b05a9 | 174 | --certpath /path/to/certfile/in/apache/nginx \ |
175 | --keypath /path/to/keyfile/in/apache/nginx \ | |
176 | --capath /path/to/ca/certfile/apache/nginx \ | |
177 | --fullchainpath path/to/fullchain/certfile/apache/nginx \ | |
178 | --reloadcmd "service apache2|nginx reload" | |
6c0ab5d2 | 179 | ``` |
7a894c4c | 180 | |
a63b05a9 | 181 | Only the domain is required, all the other parameters are optional. |
182 | ||
7a894c4c N |
183 | Install the issued cert/key to the production apache or nginx path. |
184 | ||
cbb5f7ec | 185 | 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 N |
186 | |
187 | ||
a63b05a9 | 188 | # Use Standalone server to issue cert |
189 | (requires you be root/sudoer, or you have permission to listen tcp 80 port): | |
4e1346dd | 190 | Same usage as all above, just give `no` as the webroot. |
072290f2 N |
191 | The tcp `80` port must be free to listen, otherwise you will be prompted to free the `80` port and try again. |
192 | ||
193 | ``` | |
6cc11ffb | 194 | acme.sh --issue --standalone -d aa.com -d www.aa.com -d cp.aa.com |
072290f2 N |
195 | ``` |
196 | ||
6cc11ffb | 197 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
a63b05a9 | 198 | |
199 | ||
200 | # Use Apache mode | |
201 | (requires you be root/sudoer, since it is required to interact with apache server): | |
bc1c69ff | 202 | If you are running a web server, apache or nginx, it is recommended to use the Webroot mode. |
2c75b3fd | 203 | Particularly, if you are running an apache server, you can use apache mode instead. Which doesn't write any file to your web root folder. |
204 | ||
205 | Just set string "apache" to the first argument, it will use apache plugin automatically. | |
206 | ||
207 | ``` | |
6cc11ffb | 208 | acme.sh --issue --apache -d aa.com -d www.aa.com -d user.aa.com |
2c75b3fd | 209 | ``` |
a63b05a9 | 210 | |
6cc11ffb | 211 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
2c75b3fd | 212 | |
6c0ab5d2 | 213 | |
a947dbc6 | 214 | # Use DNS mode: |
a63b05a9 | 215 | Support the dns-01 challenge. |
a947dbc6 N |
216 | |
217 | ``` | |
6cc11ffb | 218 | acme.sh --issue --dns -d aa.com -d www.aa.com -d user.aa.com |
a947dbc6 N |
219 | ``` |
220 | ||
6e89f811 | 221 | You will get the output like bellow: |
a947dbc6 N |
222 | ``` |
223 | Add the following txt record: | |
224 | Domain:_acme-challenge.aa.com | |
225 | Txt value:9ihDbjYfTExAYeDs4DBUeuTo18KBzwvTEjUnSwd32-c | |
226 | ||
227 | Add the following txt record: | |
228 | Domain:_acme-challenge.www.aa.com | |
229 | Txt value:9ihDbjxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
230 | ``` | |
231 | ||
232 | Please add those txt records to the domains. Waiting for the dns to take effect. | |
233 | ||
6e89f811 | 234 | Then just retry with 'renew' command: |
a947dbc6 N |
235 | |
236 | ``` | |
6cc11ffb | 237 | acme.sh --renew -d aa.com |
a947dbc6 N |
238 | ``` |
239 | ||
240 | Ok, it's finished. | |
241 | ||
242 | ||
08094865 | 243 | #Automatic dns api integeration |
6c0ab5d2 | 244 | |
cbb5f7ec | 245 | If your dns provider supports api access, we can use api to automatically issue certs. |
08094865 | 246 | You don't have do anything manually. |
ab497961 | 247 | |
855d9499 | 248 | ###Currently we support: |
249 | ||
cbb5f7ec | 250 | 1. Cloudflare.com api |
251 | 2. Dnspod.cn api | |
252 | 3. Cloudxns.com api | |
6cc11ffb | 253 | 4. AWS Route 53, see: https://github.com/Neilpang/acme.sh/issues/65 |
ab497961 | 254 | |
7bd9a3b1 | 255 | More apis are coming soon.... |
ab497961 | 256 | |
39c6df29 | 257 | If your dns provider is not in the supported list above, you can write your own script api easily. |
ab497961 | 258 | |
855d9499 | 259 | For more details: [How to use dns api](dnsapi) |
ab497961 | 260 | |
261 | ||
1add47a6 | 262 | # Issue ECC certificate: |
263 | LetsEncrypt now can issue ECDSA certificate. | |
264 | And we also support it. | |
265 | ||
8b92aab7 | 266 | Just set the `length` parameter with a prefix `ec-`. |
1add47a6 | 267 | For example: |
9e6c4208 N |
268 | |
269 | Single domain: | |
270 | ``` | |
6cc11ffb | 271 | acme.sh --issue -w /home/wwwroot/aa.com -d aa.com --keylength ec-256 |
1add47a6 | 272 | ``` |
9e6c4208 N |
273 | |
274 | SAN multiple domains: | |
1add47a6 | 275 | ``` |
6cc11ffb | 276 | acme.sh --issue -w /home/wwwroot/aa.com -d aa.com -d www.aa.com --keylength ec-256 |
9e6c4208 N |
277 | ``` |
278 | ||
1add47a6 | 279 | Please look at the last parameter above. |
280 | ||
281 | Valid values are: | |
282 | ||
283 | 1. ec-256 (prime256v1, "ECDSA P-256") | |
284 | 2. ec-384 (secp384r1, "ECDSA P-384") | |
8b92aab7 | 285 | 3. ec-521 (secp521r1, "ECDSA P-521", which is not supported by letsencrypt yet.) |
1add47a6 | 286 | |
287 | ||
288 | ||
6c0ab5d2 N |
289 | #Under the Hood |
290 | ||
1162f82e | 291 | Speak ACME language with bash directly to Let's encrypt. |
6c0ab5d2 N |
292 | |
293 | TODO: | |
294 | ||
295 | ||
63f04675 N |
296 | #Acknowledgment |
297 | 1. Acme-tiny: https://github.com/diafygi/acme-tiny | |
298 | 2. ACME protocol: https://github.com/ietf-wg-acme/acme | |
299 | 3. letsencrypt: https://github.com/letsencrypt/letsencrypt | |
300 | ||
301 | ||
302 | ||
6c0ab5d2 N |
303 | #License & Other |
304 | ||
305 | License is GPLv3 | |
306 | ||
1d06c947 | 307 | Please Star and Fork me. |
6c0ab5d2 | 308 | |
18ab2c5c | 309 | Issues and pull requests are welcomed. |
6c0ab5d2 N |
310 | |
311 | ||
312 |