]>
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 | |
6cc11ffb | 49 | # Upgrade from 1.x to 2.x |
2b45dba5 | 50 | |
e8cce73a | 51 | You can simply uninstall 1.x and re-install 2.x. |
2b45dba5 | 52 | 2.x is 100% compatible to 1.x. You will feel right at home as if nothing has changed. |
e8cce73a | 53 | |
6cc11ffb | 54 | # le.sh renamed to acme.sh NOW! |
6cc11ffb | 55 | |
2b45dba5 SF |
56 | All configurations are 100% compatible between `le.sh` and `acme.sh`. You just need to uninstall `le.sh` and re-install `acme.sh` again. |
57 | Nothing will be broken during the process. | |
58 | ||
59 | # How to install | |
6c0ab5d2 | 60 | |
65938b73 | 61 | ### 1. Install online: |
6c0ab5d2 | 62 | |
5bdad844 | 63 | Check this project: https://github.com/Neilpang/get.acme.sh |
b0515cf8 | 64 | |
2b45dba5 | 65 | ```bash |
99dc89c0 | 66 | curl https://get.acme.sh | sh |
90dda23f | 67 | |
68 | ``` | |
69 | ||
70 | Or: | |
2b45dba5 SF |
71 | |
72 | ```bash | |
99dc89c0 | 73 | wget -O - https://get.acme.sh | sh |
90dda23f | 74 | |
75 | ``` | |
76 | ||
77 | ||
65938b73 | 78 | ### 2. Or, Install from git: |
2b45dba5 | 79 | |
90dda23f | 80 | Clone this project: |
2b45dba5 SF |
81 | |
82 | ```bash | |
6cc11ffb | 83 | git clone https://github.com/Neilpang/acme.sh.git |
2b45dba5 | 84 | cd ./acme.sh |
6cc11ffb | 85 | ./acme.sh --install |
6c0ab5d2 | 86 | ``` |
90dda23f | 87 | |
2b45dba5 SF |
88 | You `don't have to be root` then, although `it is recommended`. |
89 | ||
d9ded9f3 | 90 | Advanced Installation: https://github.com/Neilpang/acme.sh/wiki/How-to-install |
91 | ||
2b45dba5 | 92 | The installer will perform 3 actions: |
7a894c4c | 93 | |
2b45dba5 SF |
94 | 1. Create and copy `acme.sh` to your home dir (`$HOME`): `~/.acme.sh/`. |
95 | All certs will be placed in this folder. | |
5bdad844 | 96 | 2. Create alias for: `acme.sh=~/.acme.sh/acme.sh`. |
2b45dba5 SF |
97 | 3. Create everyday cron job to check and renew the cert if needed. |
98 | ||
99 | Cron entry example: | |
100 | ||
101 | ```bash | |
102 | 0 0 * * * "/home/user/.acme.sh"/acme.sh --cron --home "/home/user/.acme.sh" > /dev/null | |
103 | ``` | |
acc1e53a | 104 | |
2b45dba5 | 105 | After the installation, you must close current terminal and reopen again to make the alias take effect. |
acc1e53a | 106 | |
cbb5f7ec | 107 | Ok, you are ready to issue cert now. |
6c0ab5d2 | 108 | Show help message: |
2b45dba5 | 109 | |
6c0ab5d2 | 110 | ``` |
39c8f79f | 111 | |
112 | root@v1:~# acme.sh -h | |
93c9216b | 113 | |
6c0ab5d2 N |
114 | ``` |
115 | ||
116 | # Just issue a cert: | |
2400e41f | 117 | |
2b45dba5 | 118 | **Example 1:** Single domain. |
2400e41f | 119 | |
2b45dba5 SF |
120 | ```bash |
121 | acme.sh --issue -d aa.com -w /home/wwwroot/aa.com | |
6c0ab5d2 | 122 | ``` |
2b45dba5 SF |
123 | |
124 | **Example 2:** Multiple domains in the same cert. | |
125 | ||
126 | ```bash | |
127 | acme.sh --issue -d aa.com -d www.aa.com -d cp.aa.com -w /home/wwwroot/aa.com | |
6c0ab5d2 | 128 | ``` |
2400e41f | 129 | |
2b45dba5 | 130 | The parameter `/home/wwwroot/aa.com` is the web root folder. You **MUST** have `write access` to this folder. |
6c0ab5d2 | 131 | |
2b45dba5 SF |
132 | Second argument **"aa.com"** is the main domain you want to issue cert for. |
133 | You must have at least a domain there. | |
6c0ab5d2 | 134 | |
2b45dba5 | 135 | You must point and bind all the domains to the same webroot dir: `/home/wwwroot/aa.com`. |
6c0ab5d2 | 136 | |
2b45dba5 | 137 | Generate/issued certs will be placed in `~/.acme.sh/aa.com/` |
6c0ab5d2 | 138 | |
7a894c4c | 139 | The issued cert will be renewed every 80 days automatically. |
6c0ab5d2 | 140 | |
6cc11ffb | 141 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
a63b05a9 | 142 | |
143 | ||
7a894c4c | 144 | # Install issued cert to apache/nginx etc. |
a63b05a9 | 145 | |
2b45dba5 SF |
146 | After you issue a cert, you probably want to install the cert with your nginx/apache or other servers you may be using. |
147 | ||
148 | ```bash | |
149 | acme.sh --installcert -d aa.com \ | |
a63b05a9 | 150 | --certpath /path/to/certfile/in/apache/nginx \ |
151 | --keypath /path/to/keyfile/in/apache/nginx \ | |
152 | --capath /path/to/ca/certfile/apache/nginx \ | |
153 | --fullchainpath path/to/fullchain/certfile/apache/nginx \ | |
154 | --reloadcmd "service apache2|nginx reload" | |
6c0ab5d2 | 155 | ``` |
7a894c4c | 156 | |
a63b05a9 | 157 | Only the domain is required, all the other parameters are optional. |
158 | ||
7a894c4c N |
159 | Install the issued cert/key to the production apache or nginx path. |
160 | ||
2b45dba5 | 161 | 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 | 162 | |
2b45dba5 | 163 | # Use Standalone server to issue cert |
6c0ab5d2 | 164 | |
2b45dba5 | 165 | **(requires you be root/sudoer, or you have permission to listen tcp 80 port)** |
072290f2 | 166 | |
2b45dba5 SF |
167 | The tcp `80` port **MUST** be free to listen, otherwise you will be prompted to free the `80` port and try again. |
168 | ||
169 | ```bash | |
170 | acme.sh --issue --standalone -d aa.com -d www.aa.com -d cp.aa.com | |
072290f2 N |
171 | ``` |
172 | ||
6cc11ffb | 173 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
a63b05a9 | 174 | |
e22bcf7c | 175 | # Use Standalone tls server to issue cert |
176 | ||
177 | **(requires you be root/sudoer, or you have permission to listen tcp 443 port)** | |
178 | ||
179 | acme.sh supports `tls-sni-01` validation. | |
180 | ||
181 | The tcp `443` port **MUST** be free to listen, otherwise you will be prompted to free the `443` port and try again. | |
182 | ||
183 | ```bash | |
184 | acme.sh --issue --tls -d aa.com -d www.aa.com -d cp.aa.com | |
185 | ``` | |
186 | ||
187 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert | |
188 | ||
2b45dba5 SF |
189 | # Use Apache mode |
190 | ||
191 | **(requires you be root/sudoer, since it is required to interact with apache server)** | |
192 | ||
193 | If you are running a web server, apache or nginx, it is recommended to use the `Webroot mode`. | |
a63b05a9 | 194 | |
2b45dba5 | 195 | 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 | 196 | |
2b45dba5 | 197 | Just set string "apache" as the second argument, it will force use of apache plugin automatically. |
2c75b3fd | 198 | |
199 | ``` | |
2b45dba5 | 200 | acme.sh --issue --apache -d aa.com -d www.aa.com -d user.aa.com |
2c75b3fd | 201 | ``` |
a63b05a9 | 202 | |
6cc11ffb | 203 | More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert |
2c75b3fd | 204 | |
a947dbc6 | 205 | # Use DNS mode: |
a947dbc6 | 206 | |
2b45dba5 SF |
207 | Support the `dns-01` challenge. |
208 | ||
209 | ```bash | |
210 | acme.sh --issue --dns -d aa.com -d www.aa.com -d user.aa.com | |
a947dbc6 N |
211 | ``` |
212 | ||
2b45dba5 SF |
213 | You should get the output like below: |
214 | ||
a947dbc6 N |
215 | ``` |
216 | Add the following txt record: | |
217 | Domain:_acme-challenge.aa.com | |
218 | Txt value:9ihDbjYfTExAYeDs4DBUeuTo18KBzwvTEjUnSwd32-c | |
219 | ||
220 | Add the following txt record: | |
221 | Domain:_acme-challenge.www.aa.com | |
222 | Txt value:9ihDbjxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
a947dbc6 N |
223 | |
224 | Please add those txt records to the domains. Waiting for the dns to take effect. | |
225 | ||
a947dbc6 | 226 | ``` |
2b45dba5 SF |
227 | |
228 | Then just rerun with `renew` argument: | |
229 | ||
230 | ```bash | |
231 | acme.sh --renew -d aa.com | |
a947dbc6 N |
232 | ``` |
233 | ||
234 | Ok, it's finished. | |
235 | ||
2b45dba5 | 236 | # Automatic DNS API integration |
a947dbc6 | 237 | |
2b45dba5 | 238 | If your DNS provider supports API access, we can use API to automatically issue the certs. |
6c0ab5d2 | 239 | |
2b45dba5 | 240 | You don't have do anything manually! |
ab497961 | 241 | |
2b45dba5 | 242 | ### Currently acme.sh supports: |
855d9499 | 243 | |
2b45dba5 SF |
244 | 1. Cloudflare.com API |
245 | 2. Dnspod.cn API | |
246 | 3. Cloudxns.com API | |
30de13b4 | 247 | 4. Godaddy.com API |
248 | 5. AWS Route 53, see: https://github.com/Neilpang/acme.sh/issues/65 | |
249 | 6. lexicon dns api: https://github.com/Neilpang/acme.sh/wiki/How-to-use-lexicon-dns-api | |
2ed01ff0 | 250 | (DigitalOcean, DNSimple, DnsMadeEasy, DNSPark, EasyDNS, Namesilo, NS1, PointHQ, Rage4 and Vultr etc.) |
ab497961 | 251 | |
2b45dba5 | 252 | ##### More APIs are coming soon... |
ab497961 | 253 | |
2b45dba5 | 254 | 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 | 255 | |
855d9499 | 256 | For more details: [How to use dns api](dnsapi) |
ab497961 | 257 | |
1add47a6 | 258 | # Issue ECC certificate: |
2b45dba5 SF |
259 | |
260 | `Let's Encrypt` now can issue **ECDSA** certificates. | |
261 | ||
1add47a6 | 262 | And we also support it. |
263 | ||
8b92aab7 | 264 | Just set the `length` parameter with a prefix `ec-`. |
2b45dba5 | 265 | |
1add47a6 | 266 | For example: |
9e6c4208 | 267 | |
2b45dba5 | 268 | ### Single domain ECC cerfiticate: |
9e6c4208 | 269 | |
2b45dba5 SF |
270 | ```bash |
271 | acme.sh --issue -w /home/wwwroot/aa.com -d aa.com --keylength ec-256 | |
1add47a6 | 272 | ``` |
2b45dba5 SF |
273 | |
274 | SAN multi domain ECC certificate: | |
275 | ||
276 | ```bash | |
277 | acme.sh --issue -w /home/wwwroot/aa.com -d aa.com -d www.aa.com --keylength ec-256 | |
9e6c4208 N |
278 | ``` |
279 | ||
1add47a6 | 280 | Please look at the last parameter above. |
281 | ||
282 | Valid values are: | |
283 | ||
2b45dba5 SF |
284 | 1. **ec-256 (prime256v1, "ECDSA P-256")** |
285 | 2. **ec-384 (secp384r1, "ECDSA P-384")** | |
286 | 3. **ec-521 (secp521r1, "ECDSA P-521", which is not supported by Let's Encrypt yet.)** | |
1add47a6 | 287 | |
2b45dba5 | 288 | # Under the Hood |
6c0ab5d2 | 289 | |
99dc89c0 | 290 | Speak ACME language using shell, directly to "Let's Encrypt". |
6c0ab5d2 N |
291 | |
292 | TODO: | |
293 | ||
2b45dba5 | 294 | # Acknowledgment |
63f04675 N |
295 | 1. Acme-tiny: https://github.com/diafygi/acme-tiny |
296 | 2. ACME protocol: https://github.com/ietf-wg-acme/acme | |
4e1f39cd | 297 | 3. Certbot: https://github.com/certbot/certbot |
63f04675 | 298 | |
2b45dba5 | 299 | # License & Other |
6c0ab5d2 N |
300 | |
301 | License is GPLv3 | |
302 | ||
1d06c947 | 303 | Please Star and Fork me. |
6c0ab5d2 | 304 | |
2b45dba5 | 305 | [Issues](https://github.com/Neilpang/acme.sh/issues) and [pull requests](https://github.com/Neilpang/acme.sh/pulls) are welcomed. |
6c0ab5d2 N |
306 | |
307 | ||
fa989a55 | 308 | # Donate |
309 | 1. PayPal: donate@acme.sh | |
6c0ab5d2 | 310 | |
d4d1f0f4 | 311 | [Donate List](https://github.com/Neilpang/acme.sh/wiki/Donate-list) |
312 |