README.md

   1 # letsencrypt.sh [![Build Status](https://travis-ci.org/lukas2511/letsencrypt.sh.svg?branch=master)](https://travis-ci.org/lukas2511/letsencrypt.sh)
   2
   3 This is a client for signing certificates with an ACME-server (currently only provided by letsencrypt) implemented as a relatively simple bash-script.
   4
   5 It uses the `openssl` utility for everything related to actually handling keys and certificates, so you need to have that installed.
   6
   7 Other dependencies are: curl, sed, grep, mktemp (all found on almost any system, curl being the only exception)
   8
   9 Current features:
  10 - Signing of a list of domains
  11 - Renewal if a certificate is about to expire or SAN (subdomains) changed
  12 - Certificate revocation
  13
  14 If you want to import existing keys from the official letsencrypt client have a look at [Import from official letsencrypt client](https://github.com/lukas2511/letsencrypt.sh/wiki/Import-from-official-letsencrypt-client).
  15
  16 Please keep in mind that this software and even the acme-protocol are relatively young and may still have some unresolved issues.
  17 Feel free to report any issues you find with this script or contribute by submitting a pullrequest.
  18
  19 ## Usage:
  20
  21 ```text
  22 Usage: ./letsencrypt.sh [-h] [command [argument]] [parameter [argument]] [parameter [argument]] ...
  23
  24 Default command: help
  25
  26 Commands:
  27  --cron (-c)                      Sign/renew non-existant/changed/expiring certificates.
  28  --revoke (-r) path/to/cert.pem   Revoke specified certificate
  29  --help (-h)                      Show help text
  30  --env (-e)                       Output configuration variables for use in other scripts
  31
  32 Parameters:
  33  --domain (-d) domain.tld         Use specified domain name(s) instead of domains.txt entry (one certificate!)
  34  --force (-x)                     Force renew of certificate even if it is longer valid than value in RENEW_DAYS
  35  --privkey (-p) path/to/key.pem   Use specified private key instead of account key (useful for revocation)
  36  --config (-f) path/to/config.sh  Use specified config file
  37  --hook (-k) path/to/hook.sh      Use specified script for hooks
  38  --challenge (-t) http-01|dns-01  Which challenge should be used? Currently http-01 and dns-01 are supported
  39 ```
  40
  41 ### domains.txt
  42
  43 The file `domains.txt` should have the following format:
  44
  45 ```text
  46 example.com www.example.com
  47 example.net www.example.net wiki.example.net
  48 ```
  49
  50 This states that there should be two certificates `example.com` and `example.net`,
  51 with the other domains in the corresponding line being their alternative names.
  52
  53 ### $WELLKNOWN / challenge-response
  54
  55 Boulder (acme-server) is looking for challenge responses under your domain in the `.well-known/acme-challenge` directory
  56
  57 This script uses `http-01`-type verification (for now) so you need to have that directory available over normal http (no ssl).
  58
  59 A full URL would look like `http://example.org/.well-known/acme-challenge/c3VjaC1jaGFsbGVuZ2UtbXVjaA-aW52YWxpZC13b3c`.
  60
  61 An example setup to get this to work would be:
  62
  63 nginx.conf:
  64 ```
  65 ...
  66 location /.well-known/acme-challenge {
  67   alias /var/www/letsencrypt;
  68 }
  69 ...
  70 ```
  71
  72 config.sh:
  73 ```bash
  74 ...
  75 WELLKNOWN="/var/www/letsencrypt"
  76 ...
  77 ```
  78
  79 An alternative to setting the WELLKNOWN variable would be to create a symlink to the default location next to the script (or BASEDIR):
  80 `ln -s /var/www/letsencrypt .acme-challenges`
  81
  82 ### dns-01 challenge
  83
  84 This script also supports the new `dns-01`-type verification. Be aware that at the moment this is not available on the production servers from letsencrypt. Please read https://community.letsencrypt.org/t/dns-challenge-is-in-staging/8322 for the current state of `dns-01` support.
  85
  86 You need a hook script that deploys the challenge to your DNS server!
  87
  88 ### Elliptic Curve Cryptography (ECC)
  89
  90 This script also supports certificates with Elliptic Curve public keys! Be aware that at the moment this is not available on the production servers from letsencrypt. Please read https://community.letsencrypt.org/t/ecdsa-testing-on-staging/8809/ for the current state of ECC support.