README.md

   1 # le: means simp`Le`
   2 Simplest shell script for LetsEncrypt free Certificate client
   3
   4 Simple and Powerful, you only need 3 minutes to learn.
   5
   6 Pure written in bash, no dependencies to python, acme-tiny or LetsEncrypt official client.
   7 Just one script, to issue, renew your certificates automatically.
   8
   9 Probably it's the smallest&easiest&smartest shell script to automatically issue & renew the free certificates from LetsEncrypt.
  10
  11 Do NOT require to be `root/sudoer`.
  12
  13 #Tested OS
  14 1. Ubuntu/Debian.
  15 2. CentOS
  16 3. Windows (cygwin with curl, openssl and crontab included)
  17 4. FreeBSD with bash
  18 5. pfsense with bash and curl
  19
  20
  21 #Supported Mode
  22 1. Webroot mode
  23 2. Standalone mode
  24 3. Apache mode
  25 4. Dns mode
  26
  27 #How to use
  28
  29 1. Clone this project: https://github.com/Neilpang/le.git
  30
  31 2. Install le:
  32 ```
  33 ./le.sh install
  34 ```
  35 You don't have to be root then, although it is recommended.
  36
  37 Which does 3 jobs:
  38 * create and copy `le.sh` to your home dir:  `~/.le`
  39 All the certs will be placed in this folder.
  40 * create alias : `le.sh=~/.le/le.sh` and `le=~/.le/le.sh`.
  41 * create everyday cron job to check and renew the cert if needed.
  42
  43 After install, you must close current terminal and reopen again to make the alias take effect.
  44
  45 Ok, you are ready to issue cert now.
  46 Show help message:
  47 ```
  48 root@v1:~# le.sh
  49 https://github.com/Neilpang/le
  50 v1.1.1
  51 Usage: le.sh  [command] ...[args]....
  52 Available commands:
  53
  54 install:
  55   Install le.sh to your system.
  56 issue:
  57   Issue a cert.
  58 installcert:
  59   Install the issued cert to apache/nginx or any other server.
  60 renew:
  61   Renew a cert.
  62 renewAll:
  63   Renew all the certs.
  64 uninstall:
  65   Uninstall le.sh, and uninstall the cron job.
  66 version:
  67   Show version info.
  68 installcronjob:
  69   Install the cron job to renew certs, you don't need to call this. The 'install' command can automatically install the cron job.
  70 uninstallcronjob:
  71   Uninstall the cron job. The 'uninstall' command can do this automatically.
  72 createAccountKey:
  73   Create an account private key, professional use.
  74 createDomainKey:
  75   Create an domain private key, professional use.
  76 createCSR:
  77   Create CSR , professional use.
  78
  79
  80 root@v1:~/le# le issue
  81 Usage: le  issue  webroot|no|apache|dns   a.com  [www.a.com,b.com,c.com]|no   [key-length]|no
  82
  83
  84 ```
  85
  86 Set the param value to "no" means you want to ignore it.
  87
  88 For example, if you give "no" to "key-length", it will use default length 2048.
  89
  90 And if you give 'no' to 'cert-file-path', it will not copy the issued cert to the "cert-file-path".
  91
  92 In all the cases, the issued cert will be placed in "~/.le/domain.com/"
  93
  94
  95 # Just issue a cert:
  96 Example 1:
  97 Only one domain:
  98 ```
  99 le issue   /home/wwwroot/aa.com    aa.com
 100 ```
 101
 102 Example 2:
 103 Multiple domains in the same cert:
 104
 105 ```
 106 le issue   /home/wwwroot/aa.com    aa.com    www.aa.com,cp.aa.com
 107 ```
 108
 109 First argument `/home/wwwroot/aa.com` is the web root folder, You must have `write` access to this folder.
 110
 111 Second argument "aa.com" is the main domain you want to issue cert for.
 112
 113 Third argument is the additional domain list you want to use. Comma separated list,  which is Optional.
 114
 115 You must point and bind all the domains to the same webroot dir:`/home/wwwroot/aa.com`
 116
 117 The cert will be placed in `~/.le/aa.com/`
 118
 119 The issued cert will be renewed every 80 days automatically.
 120
 121 # Install issued cert to apache/nginx etc.
 122 ```
 123 le installcert  aa.com /path/to/certfile/in/apache/nginx  /path/to/keyfile/in/apache/nginx  /path/to/ca/certfile/apache/nginx   "service apache2|nginx reload"
 124 ```
 125
 126 Install the issued cert/key to the production apache or nginx path.
 127
 128 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`
 129
 130
 131 # Use Standalone server to issue cert (requires you be root/sudoer, or you have permission to listen tcp 80 port):
 132 Same usage as all above,  just give `no` as the webroot.
 133 The tcp `80` port must be free to listen, otherwise you will be prompted to free the `80` port and try again.
 134
 135 ```
 136 le issue    no    aa.com    www.aa.com,cp.aa.com
 137 ```
 138
 139 # Use Apache mode (requires you be root/sudoer, since it is required to interact with apache server):
 140 If you are running a web server, apache or nginx, it is recommended to use the Webroot mode.
 141 Particularly,  if you are running an apache server, you can use apache mode instead. Which doesn't write any file to your web root folder.
 142
 143 Just set string "apache" to the first argument, it will use apache plugin automatically.
 144
 145 ```
 146 le  issue  apache  aa.com   www.aa.com,user.aa.com
 147 ```
 148 All the other arguments are the same with previous.
 149
 150
 151 # Use DNS mode:
 152 Support the latest dns-01 challenge.
 153
 154 ```
 155 le  issue   dns   aa.com  www.aa.com,user.aa.com
 156 ```
 157
 158 You will get the output like bellow:
 159 ```
 160 Add the following txt record:
 161 Domain:_acme-challenge.aa.com
 162 Txt value:9ihDbjYfTExAYeDs4DBUeuTo18KBzwvTEjUnSwd32-c
 163
 164 Add the following txt record:
 165 Domain:_acme-challenge.www.aa.com
 166 Txt value:9ihDbjxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 167 ```
 168
 169 Please add those txt records to the domains. Waiting for the dns to take effect.
 170
 171 Then just retry with 'renew' command:
 172
 173 ```
 174 le renew  aa.com
 175 ```
 176
 177 Ok, it's finished.
 178
 179
 180 #Automatic dns api integeration
 181
 182 If your dns provider supports api access, we can use api to automatically issue certs.
 183 You don't have do anything manually.
 184
 185 ###Currently we support:
 186
 187 1. Cloudflare.com api
 188 2. Dnspod.cn api
 189 3. Cloudxns.com api
 190 4. AWS Route 53, see: https://github.com/Neilpang/le/issues/65
 191
 192 More apis are coming soon....
 193
 194 If your dns provider is not in the supported list above, you can write your own script api easily.
 195
 196 For more details: [How to use dns api](dnsapi)
 197
 198
 199 # Issue ECC certificate:
 200 LetsEncrypt now can issue ECDSA certificate.
 201 And we also support it.
 202
 203 Just set the `length` parameter with a prefix `ec-`.
 204 For example:
 205
 206 Single domain:
 207 ```
 208 le issue  /home/wwwroot/aa.com    aa.com   no      ec-256
 209 ```
 210
 211 SAN multiple domains:
 212 ```
 213 le issue  /home/wwwroot/aa.com    aa.com   www.aa.com,cp.aa.com    ec-256
 214 ```
 215
 216 Please look at the last parameter above.
 217
 218 Valid values are:
 219
 220 1. ec-256 (prime256v1,  "ECDSA P-256")
 221 2. ec-384 (secp384r1,   "ECDSA P-384")
 222 3. ec-521 (secp521r1,   "ECDSA P-521", which is not supported by letsencrypt yet.)
 223
 224
 225
 226 #Under the Hood
 227
 228 Speak ACME language with bash directly to Let's encrypt.
 229
 230 TODO:
 231
 232
 233 #Acknowledgment
 234 1. Acme-tiny: https://github.com/diafygi/acme-tiny
 235 2. ACME protocol: https://github.com/ietf-wg-acme/acme
 236 3. letsencrypt: https://github.com/letsencrypt/letsencrypt
 237
 238
 239
 240 #License & Other
 241
 242 License is GPLv3
 243
 244 Please Star and Fork me.
 245
 246 Issues and pull requests are welcomed.
 247
 248
 249