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 |18|[![](https://cdn.rawgit.com/Neilpang/acmetest/master/status/solaris.svg)](https://github.com/Neilpang/letest#here-are-the-latest-status)|SunOS/Solaris
  37
  38 For all build statuses, check our [daily build project](https://github.com/Neilpang/acmetest):
  39
  40 https://github.com/Neilpang/acmetest
  41
  42 # Supported Mode
  43
  44 1. Webroot mode
  45 2. Standalone mode
  46 3. Apache mode
  47 4. Dns mode
  48
  49 # Upgrade from 1.x to 2.x
  50
  51 You can simply uninstall 1.x and re-install 2.x.
  52 2.x is 100% compatible to 1.x. You will feel right at home as if nothing has changed.
  53
  54 # le.sh renamed to acme.sh NOW!
  55
  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
  60
  61 ### 1. Install online:
  62
  63 Check this project: https://github.com/Neilpang/get.acme.sh
  64
  65 ```bash
  66 curl https://get.acme.sh | sh
  67
  68 ```
  69
  70 Or:
  71
  72 ```bash
  73 wget -O -  https://get.acme.sh | sh
  74
  75 ```
  76
  77
  78 ### 2. Or, Install from git:
  79
  80 Clone this project:
  81
  82 ```bash
  83 git clone https://github.com/Neilpang/acme.sh.git
  84 cd ./acme.sh
  85 ./acme.sh --install
  86 ```
  87
  88 You `don't have to be root` then, although `it is recommended`.
  89
  90 Advanced Installation:  https://github.com/Neilpang/acme.sh/wiki/How-to-install
  91
  92 The installer will perform 3 actions:
  93
  94 1. Create and copy `acme.sh` to your home dir (`$HOME`):  `~/.acme.sh/`.
  95 All certs will be placed in this folder.
  96 2. Create alias for: `acme.sh=~/.acme.sh/acme.sh`.
  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 ```
 104
 105 After the installation, you must close current terminal and reopen again to make the alias take effect.
 106
 107 Ok, you are ready to issue cert now.
 108 Show help message:
 109
 110 ```
 111
 112 root@v1:~# acme.sh -h
 113
 114 ```
 115
 116 # Just issue a cert:
 117
 118 **Example 1:** Single domain.
 119
 120 ```bash
 121 acme.sh --issue -d aa.com -w /home/wwwroot/aa.com
 122 ```
 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
 128 ```
 129
 130 The parameter `/home/wwwroot/aa.com` is the web root folder. You **MUST** have `write access` to this folder.
 131
 132 Second argument **"aa.com"** is the main domain you want to issue cert for.
 133 You must have at least a domain there.
 134
 135 You must point and bind all the domains to the same webroot dir: `/home/wwwroot/aa.com`.
 136
 137 Generate/issued certs will be placed in `~/.acme.sh/aa.com/`
 138
 139 The issued cert will be renewed every 80 days automatically.
 140
 141 More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert
 142
 143
 144 # Install issued cert to apache/nginx etc.
 145
 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 \
 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"
 155 ```
 156
 157 Only the domain is required, all the other parameters are optional.
 158
 159 Install the issued cert/key to the production apache or nginx path.
 160
 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`.
 162
 163 # Use Standalone server to issue cert
 164
 165 **(requires you be root/sudoer, or you have permission to listen tcp 80 port)**
 166
 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
 171 ```
 172
 173 More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert
 174
 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
 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`.
 194
 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.
 196
 197 Just set string "apache" as the second argument, it will force use of apache plugin automatically.
 198
 199 ```
 200 acme.sh --issue --apache -d aa.com -d www.aa.com -d user.aa.com
 201 ```
 202
 203 More examples: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert
 204
 205 # Use DNS mode:
 206
 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
 211 ```
 212
 213 You should get the output like below:
 214
 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
 223
 224 Please add those txt records to the domains. Waiting for the dns to take effect.
 225
 226 ```
 227
 228 Then just rerun with `renew` argument:
 229
 230 ```bash
 231 acme.sh --renew -d aa.com
 232 ```
 233
 234 Ok, it's finished.
 235
 236 # Automatic DNS API integration
 237
 238 If your DNS provider supports API access, we can use API to automatically issue the certs.
 239
 240 You don't have do anything manually!
 241
 242 ### Currently acme.sh supports:
 243
 244 1. Cloudflare.com API
 245 2. Dnspod.cn API
 246 3. Cloudxns.com API
 247 4. Godaddy.com API
 248 5. OVH, kimsufi, soyoustart and runabove API
 249 6. AWS Route 53, see: https://github.com/Neilpang/acme.sh/issues/65
 250 7. lexicon dns api: https://github.com/Neilpang/acme.sh/wiki/How-to-use-lexicon-dns-api
 251    (DigitalOcean, DNSimple, DnsMadeEasy, DNSPark, EasyDNS, Namesilo, NS1, PointHQ, Rage4 and Vultr etc.)
 252
 253 ##### More APIs are coming soon...
 254
 255 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.
 256
 257 For more details: [How to use dns api](dnsapi)
 258
 259 # Issue ECC certificate:
 260
 261 `Let's Encrypt` now can issue **ECDSA** certificates.
 262
 263 And we also support it.
 264
 265 Just set the `length` parameter with a prefix `ec-`.
 266
 267 For example:
 268
 269 ### Single domain ECC cerfiticate:
 270
 271 ```bash
 272 acme.sh --issue -w /home/wwwroot/aa.com -d aa.com --keylength  ec-256
 273 ```
 274
 275 SAN multi domain ECC certificate:
 276
 277 ```bash
 278 acme.sh --issue -w /home/wwwroot/aa.com -d aa.com -d www.aa.com --keylength  ec-256
 279 ```
 280
 281 Please look at the last parameter above.
 282
 283 Valid values are:
 284
 285 1. **ec-256 (prime256v1, "ECDSA P-256")**
 286 2. **ec-384 (secp384r1,  "ECDSA P-384")**
 287 3. **ec-521 (secp521r1,  "ECDSA P-521", which is not supported by Let's Encrypt yet.)**
 288
 289 # Under the Hood
 290
 291 Speak ACME language using shell, directly to "Let's Encrypt".
 292
 293 TODO:
 294
 295 # Acknowledgment
 296 1. Acme-tiny: https://github.com/diafygi/acme-tiny
 297 2. ACME protocol: https://github.com/ietf-wg-acme/acme
 298 3. Certbot: https://github.com/certbot/certbot
 299
 300 # License & Other
 301
 302 License is GPLv3
 303
 304 Please Star and Fork me.
 305
 306 [Issues](https://github.com/Neilpang/acme.sh/issues) and [pull requests](https://github.com/Neilpang/acme.sh/pulls) are welcomed.
 307
 308
 309 # Donate
 310 1. PayPal:  donate@acme.sh
 311
 312 [Donate List](https://github.com/Neilpang/acme.sh/wiki/Donate-list)
 313