You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

461 lines
16 KiB

8 years ago
8 years ago
9 years ago
8 years ago
9 years ago
9 years ago
9 years ago
8 years ago
8 years ago
8 years ago
8 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
8 years ago
8 years ago
9 years ago
8 years ago
9 years ago
9 years ago
8 years ago
8 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
8 years ago
9 years ago
9 years ago
8 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
8 years ago
8 years ago
8 years ago
8 years ago
9 years ago
8 years ago
9 years ago
8 years ago
9 years ago
8 years ago
9 years ago
9 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
9 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
9 years ago
9 years ago
8 years ago
9 years ago
9 years ago
9 years ago
8 years ago
9 years ago
9 years ago
9 years ago
9 years ago
8 years ago
9 years ago
8 years ago
  1. # An ACME Shell script: acme.sh [![Build Status](https://travis-ci.org/Neilpang/acme.sh.svg?branch=master)](https://travis-ci.org/Neilpang/acme.sh)
  2. [![Join the chat at https://gitter.im/acme-sh/Lobby](https://badges.gitter.im/acme-sh/Lobby.svg)](https://gitter.im/acme-sh/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
  3. - An ACME protocol client written purely in Shell (Unix shell) language.
  4. - Full ACME protocol implementation.
  5. - Simple, powerful and very easy to use. You only need 3 minutes to learn it.
  6. - Bash, dash and sh compatible.
  7. - Simplest shell script for Let's Encrypt free certificate client.
  8. - Purely written in Shell with no dependencies on python or the official Let's Encrypt client.
  9. - Just one script to issue, renew and install your certificates automatically.
  10. - DOES NOT require `root/sudoer` access.
  11. - Docker friendly
  12. - IPv6 support
  13. It's probably the `easiest & smartest` shell script to automatically issue & renew the free certificates from Let's Encrypt.
  14. Wiki: https://github.com/Neilpang/acme.sh/wiki
  15. For Docker Fans: [acme.sh :two_hearts: Docker ](https://github.com/Neilpang/acme.sh/wiki/Run-acme.sh-in-docker)
  16. Twitter: [@neilpangxa](https://twitter.com/neilpangxa)
  17. # [中文说明](https://github.com/Neilpang/acme.sh/wiki/%E8%AF%B4%E6%98%8E)
  18. # Who are using **acme.sh**
  19. - [FreeBSD.org](https://blog.crashed.org/letsencrypt-in-freebsd-org/)
  20. - [ruby-china.org](https://ruby-china.org/topics/31983)
  21. - [Proxmox](https://pve.proxmox.com/wiki/HTTPS_Certificate_Configuration_(Version_4.x_and_newer))
  22. - [pfsense](https://github.com/pfsense/FreeBSD-ports/pull/89)
  23. - [webfaction](https://community.webfaction.com/questions/19988/using-letsencrypt)
  24. - [Loadbalancer.org](https://www.loadbalancer.org/blog/loadbalancer-org-with-lets-encrypt-quick-and-dirty)
  25. - [discourse.org](https://meta.discourse.org/t/setting-up-lets-encrypt/40709)
  26. - [Centminmod](http://centminmod.com/letsencrypt-acmetool-https.html)
  27. - [splynx](https://forum.splynx.com/t/free-ssl-cert-for-splynx-lets-encrypt/297)
  28. - [archlinux](https://aur.archlinux.org/packages/acme.sh-git/)
  29. - [opnsense.org](https://github.com/opnsense/plugins/tree/master/security/acme-client/src/opnsense/scripts/OPNsense/AcmeClient)
  30. - [more...](https://github.com/Neilpang/acme.sh/wiki/Blogs-and-tutorials)
  31. # Tested OS
  32. | NO | Status| Platform|
  33. |----|-------|---------|
  34. |1|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/ubuntu-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)| Ubuntu
  35. |2|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/debian-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)| Debian
  36. |3|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/centos-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|CentOS
  37. |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)
  38. |5|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/freebsd.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|FreeBSD
  39. |6|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/pfsense.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|pfsense
  40. |7|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/opensuse-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|openSUSE
  41. |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)
  42. |9|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/base-archlinux.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|Archlinux
  43. |10|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/fedora-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|fedora
  44. |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
  45. |12|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/oraclelinux-latest.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|Oracle Linux
  46. |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
  47. |14|-----| Cloud Linux https://github.com/Neilpang/le/issues/111
  48. |15|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/openbsd.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|OpenBSD
  49. |16|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/mageia.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|Mageia
  50. |17|-----| OpenWRT: Tested and working. See [wiki page](https://github.com/Neilpang/acme.sh/wiki/How-to-run-on-OpenWRT)
  51. |18|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/solaris.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|SunOS/Solaris
  52. |19|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/gentoo-stage3-amd64.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|Gentoo Linux
  53. |20|[![Build Status](https://travis-ci.org/Neilpang/acme.sh.svg?branch=master)](https://travis-ci.org/Neilpang/acme.sh)|Mac OSX
  54. For all build statuses, check our [weekly build project](https://github.com/Neilpang/acmetest):
  55. https://github.com/Neilpang/acmetest
  56. # Supported modes
  57. - Webroot mode
  58. - Standalone mode
  59. - Apache mode
  60. - Nginx mode ( Beta )
  61. - DNS mode
  62. - [Stateless mode](https://github.com/Neilpang/acme.sh/wiki/Stateless-Mode)
  63. # 1. How to install
  64. ### 1. Install online
  65. Check this project: https://github.com/Neilpang/get.acme.sh
  66. ```bash
  67. curl https://get.acme.sh | sh
  68. ```
  69. Or:
  70. ```bash
  71. wget -O - https://get.acme.sh | sh
  72. ```
  73. ### 2. Or, Install from git
  74. Clone this project and launch installation:
  75. ```bash
  76. git clone https://github.com/Neilpang/acme.sh.git
  77. cd ./acme.sh
  78. ./acme.sh --install
  79. ```
  80. You `don't have to be root` then, although `it is recommended`.
  81. Advanced Installation: https://github.com/Neilpang/acme.sh/wiki/How-to-install
  82. The installer will perform 3 actions:
  83. 1. Create and copy `acme.sh` to your home dir (`$HOME`): `~/.acme.sh/`.
  84. All certs will be placed in this folder too.
  85. 2. Create alias for: `acme.sh=~/.acme.sh/acme.sh`.
  86. 3. Create daily cron job to check and renew the certs if needed.
  87. Cron entry example:
  88. ```bash
  89. 0 0 * * * "/home/user/.acme.sh"/acme.sh --cron --home "/home/user/.acme.sh" > /dev/null
  90. ```
  91. After the installation, you must close the current terminal and reopen it to make the alias take effect.
  92. Ok, you are ready to issue certs now.
  93. Show help message:
  94. ```
  95. root@v1:~# acme.sh -h
  96. ```
  97. # 2. Just issue a cert
  98. **Example 1:** Single domain.
  99. ```bash
  100. acme.sh --issue -d example.com -w /home/wwwroot/example.com
  101. ```
  102. or:
  103. ```bash
  104. acme.sh --issue -d example.com -w /home/username/public_html
  105. ```
  106. or:
  107. ```bash
  108. acme.sh --issue -d example.com -w /var/www/html
  109. ```
  110. **Example 2:** Multiple domains in the same cert.
  111. ```bash
  112. acme.sh --issue -d example.com -d www.example.com -d cp.example.com -w /home/wwwroot/example.com
  113. ```
  114. The parameter `/home/wwwroot/example.com` or `/home/username/public_html` or `/var/www/html` is the web root folder where you host your website files. You **MUST** have `write access` to this folder.
  115. Second argument **"example.com"** is the main domain you want to issue the cert for.
  116. You must have at least one domain there.
  117. You must point and bind all the domains to the same webroot dir: `/home/wwwroot/example.com`.
  118. Generated/issued certs will be placed in `~/.acme.sh/example.com/`
  119. The issued cert will be renewed automatically every **60** days.
  120. More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert
  121. # 3. Install the issued cert to Apache/Nginx etc.
  122. After you issue a cert, you probably want to install/copy the cert to your Apache/Nginx or other servers.
  123. You **MUST** use this command to copy the certs to the target files, **DO NOT** use the certs files in **~/.acme.sh/** folder, they are for internal use only, the folder structure may change in the future.
  124. **Apache** example:
  125. ```bash
  126. acme.sh --install-cert -d example.com \
  127. --cert-file /path/to/certfile/in/apache/cert.pem \
  128. --key-file /path/to/keyfile/in/apache/key.pem \
  129. --fullchain-file /path/to/fullchain/certfile/apache/fullchain.pem \
  130. --reloadcmd "service apache2 force-reload"
  131. ```
  132. **Nginx** example:
  133. ```bash
  134. acme.sh --install-cert -d example.com \
  135. --key-file /path/to/keyfile/in/nginx/key.pem \
  136. --fullchain-file /path/to/fullchain/nginx/cert.pem \
  137. --reloadcmd "service nginx force-reload"
  138. ```
  139. Only the domain is required, all the other parameters are optional.
  140. The ownership and permission info of existing files are preserved. You may want to precreate the files to have defined ownership and permission.
  141. Install/copy the issued cert/key to the production Apache or Nginx path.
  142. The cert will be renewed every **60** days by default (which is configurable). Once the cert is renewed, the Apache/Nginx service will be reloaded automatically by the command: `service apache2 force-reload` or `service nginx force-reload`.
  143. # 4. Use Standalone server to issue cert
  144. **(requires you to be root/sudoer or have permission to listen on port 80 (TCP))**
  145. Port `80` (TCP) **MUST** be free to listen on, otherwise you will be prompted to free it and try again.
  146. ```bash
  147. acme.sh --issue --standalone -d example.com -d www.example.com -d cp.example.com
  148. ```
  149. More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert
  150. # 5. Use Standalone TLS server to issue cert
  151. **(requires you to be root/sudoer or have permission to listen on port 443 (TCP))**
  152. acme.sh supports `tls-sni-01` validation.
  153. Port `443` (TCP) **MUST** be free to listen on, otherwise you will be prompted to free it and try again.
  154. ```bash
  155. acme.sh --issue --tls -d example.com -d www.example.com -d cp.example.com
  156. ```
  157. More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert
  158. # 6. Use Apache mode
  159. **(requires you to be root/sudoer, since it is required to interact with Apache server)**
  160. If you are running a web server, Apache or Nginx, it is recommended to use the `Webroot mode`.
  161. 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.
  162. Just set string "apache" as the second argument and it will force use of apache plugin automatically.
  163. ```
  164. acme.sh --issue --apache -d example.com -d www.example.com -d cp.example.com
  165. ```
  166. More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert
  167. # 7. Use Nginx mode
  168. **(requires you to be root/sudoer, since it is required to interact with Nginx server)**
  169. If you are running a web server, Apache or Nginx, it is recommended to use the `Webroot mode`.
  170. Particularly, if you are running an nginx server, you can use nginx mode instead. This mode doesn't write any files to your web root folder.
  171. Just set string "nginx" as the second argument.
  172. It will configure nginx server automatically to verify the domain and then restore the nginx config to the original version.
  173. So, the config is not changed.
  174. ```
  175. acme.sh --issue --nginx -d example.com -d www.example.com -d cp.example.com
  176. ```
  177. More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert
  178. # 8. Use DNS mode:
  179. Support the `dns-01` challenge.
  180. ```bash
  181. acme.sh --issue --dns -d example.com -d www.example.com -d cp.example.com
  182. ```
  183. You should get an output like below:
  184. ```
  185. Add the following txt record:
  186. Domain:_acme-challenge.example.com
  187. Txt value:9ihDbjYfTExAYeDs4DBUeuTo18KBzwvTEjUnSwd32-c
  188. Add the following txt record:
  189. Domain:_acme-challenge.www.example.com
  190. Txt value:9ihDbjxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  191. Please add those txt records to the domains. Waiting for the dns to take effect.
  192. ```
  193. Then just rerun with `renew` argument:
  194. ```bash
  195. acme.sh --renew -d example.com
  196. ```
  197. Ok, it's finished.
  198. **Take care, this is dns manual mode, it can not be renewed automatically. you will have to add a new txt record to your domain by your hand when you renew your cert.**
  199. **Please use dns api mode instead.**
  200. # 9. Automatic DNS API integration
  201. If your DNS provider supports API access, we can use that API to automatically issue the certs.
  202. You don't have to do anything manually!
  203. ### Currently acme.sh supports:
  204. 1. CloudFlare.com API
  205. 1. DNSPod.cn API
  206. 1. CloudXNS.com API
  207. 1. GoDaddy.com API
  208. 1. PowerDNS.com API
  209. 1. OVH, kimsufi, soyoustart and runabove API
  210. 1. nsupdate API
  211. 1. LuaDNS.com API
  212. 1. DNSMadeEasy.com API
  213. 1. AWS Route 53
  214. 1. aliyun.com(阿里云) API
  215. 1. ISPConfig 3.1 API
  216. 1. Alwaysdata.com API
  217. 1. Linode.com API
  218. 1. FreeDNS (https://freedns.afraid.org/)
  219. 1. cyon.ch
  220. 1. Domain-Offensive/Resellerinterface/Domainrobot API
  221. 1. Gandi LiveDNS API
  222. 1. Knot DNS API
  223. 1. DigitalOcean API (native)
  224. 1. ClouDNS.net API
  225. 1. Infoblox NIOS API (https://www.infoblox.com/)
  226. 1. VSCALE (https://vscale.io/)
  227. 1. Dynu API (https://www.dynu.com)
  228. 1. DNSimple API
  229. 1. NS1.com API
  230. 1. DuckDNS.org API
  231. 1. Name.com API
  232. And:
  233. 1. lexicon DNS API: https://github.com/Neilpang/acme.sh/wiki/How-to-use-lexicon-dns-api
  234. (DigitalOcean, DNSimple, DNSMadeEasy, DNSPark, EasyDNS, Namesilo, NS1, PointHQ, Rage4 and Vultr etc.)
  235. **More APIs coming soon...**
  236. If your DNS provider is not on the supported list above, you can write your own DNS API script easily. If you do, please consider submitting a [Pull Request](https://github.com/Neilpang/acme.sh/pulls) and contribute it to the project.
  237. For more details: [How to use DNS API](dnsapi)
  238. # 10. Issue ECC certificates
  239. `Let's Encrypt` can now issue **ECDSA** certificates.
  240. And we support them too!
  241. Just set the `length` parameter with a prefix `ec-`.
  242. For example:
  243. ### Single domain ECC certificate
  244. ```bash
  245. acme.sh --issue -w /home/wwwroot/example.com -d example.com --keylength ec-256
  246. ```
  247. ### SAN multi domain ECC certificate
  248. ```bash
  249. acme.sh --issue -w /home/wwwroot/example.com -d example.com -d www.example.com --keylength ec-256
  250. ```
  251. Please look at the last parameter above.
  252. Valid values are:
  253. 1. **ec-256 (prime256v1, "ECDSA P-256")**
  254. 2. **ec-384 (secp384r1, "ECDSA P-384")**
  255. 3. **ec-521 (secp521r1, "ECDSA P-521", which is not supported by Let's Encrypt yet.)**
  256. # 11. How to renew the issued certs
  257. No, you don't need to renew the certs manually. All the certs will be renewed automatically every **60** days.
  258. However, you can also force to renew any cert:
  259. ```
  260. acme.sh --renew -d example.com --force
  261. ```
  262. or, for ECC cert:
  263. ```
  264. acme.sh --renew -d example.com --force --ecc
  265. ```
  266. # 12. How to upgrade `acme.sh`
  267. acme.sh is in constant development, so it's strongly recommended to use the latest code.
  268. You can update acme.sh to the latest code:
  269. ```
  270. acme.sh --upgrade
  271. ```
  272. You can also enable auto upgrade:
  273. ```
  274. acme.sh --upgrade --auto-upgrade
  275. ```
  276. Then **acme.sh** will be kept up to date automatically.
  277. Disable auto upgrade:
  278. ```
  279. acme.sh --upgrade --auto-upgrade 0
  280. ```
  281. # 13. Issue a cert from an existing CSR
  282. https://github.com/Neilpang/acme.sh/wiki/Issue-a-cert-from-existing-CSR
  283. # 14. Under the Hood
  284. Speak ACME language using shell, directly to "Let's Encrypt".
  285. TODO:
  286. # 15. Acknowledgments
  287. 1. Acme-tiny: https://github.com/diafygi/acme-tiny
  288. 2. ACME protocol: https://github.com/ietf-wg-acme/acme
  289. 3. Certbot: https://github.com/certbot/certbot
  290. # 16. License & Others
  291. License is GPLv3
  292. Please Star and Fork me.
  293. [Issues](https://github.com/Neilpang/acme.sh/issues) and [pull requests](https://github.com/Neilpang/acme.sh/pulls) are welcome.
  294. # 17. Donate
  295. Your donation makes **acme.sh** better:
  296. 1. PayPal/Alipay(支付宝)/Wechat(微信): [https://donate.acme.sh/](https://donate.acme.sh/)
  297. [Donate List](https://github.com/Neilpang/acme.sh/wiki/Donate-list)