README.md

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