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