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 Please keep in mind that this software and even the acme-protocol are relatively young and may still have some unresolved issues.
  15 Feel free to report any issues you find with this script or contribute by submitting a pullrequest.
  16
  17 ## Usage:
  18
  19 ```text
  20 Usage: ./letsencrypt.sh [-h] [command [argument]] [parameter [argument]] [parameter [argument]] ...
  21
  22 Default command: help
  23
  24 Commands:
  25  --cron (-c)                      Sign/renew non-existant/changed/expiring certificates.
  26  --revoke (-r) path/to/cert.pem   Revoke specified certificate
  27  --help (-h)                      Show help text
  28  --env (-e)                       Output configuration variables for use in other scripts
  29
  30 Parameters:
  31  --domain (-d) domain.tld         Use specified domain name(s) instead of domains.txt entry (one certificate!)
  32  --force (-x)                     Force renew of certificate even if it is longer valid than value in RENEW_DAYS
  33  --privkey (-p) path/to/key.pem   Use specified private key instead of account key (useful for revocation)
  34  --config (-f) path/to/config.sh  Use specified config file
  35  --hook (-k) path/to/hook.sh      Use specified script for hooks
  36  --challenge (-t) http-01|dns-01  Which challenge should be used? Currently http-01 and dns-01 are supported
  37 ```
  38
  39 ### domains.txt
  40
  41 The file `domains.txt` should have the following format:
  42
  43 ```text
  44 example.com www.example.com
  45 example.net www.example.net wiki.example.net
  46 ```
  47
  48 This states that there should be two certificates `example.com` and `example.net`,
  49 with the other domains in the corresponding line being their alternative names.
  50
  51 ### $WELLKNOWN / challenge-response
  52
  53 Boulder (acme-server) is looking for challenge responses under your domain in the `.well-known/acme-challenge` directory
  54
  55 This script uses `http-01`-type verification (for now) so you need to have that directory available over normal http (no ssl).
  56
  57 A full URL would look like `http://example.org/.well-known/acme-challenge/c3VjaC1jaGFsbGVuZ2UtbXVjaA-aW52YWxpZC13b3c`.
  58
  59 An example setup to get this to work would be:
  60
  61 nginx.conf:
  62 ```
  63 ...
  64 location /.well-known/acme-challenge {
  65   alias /var/www/letsencrypt;
  66 }
  67 ...
  68 ```
  69
  70 config.sh:
  71 ```bash
  72 ...
  73 WELLKNOWN="/var/www/letsencrypt"
  74 ...
  75 ```
  76
  77 An alternative to setting the WELLKNOWN variable would be to create a symlink to the default location next to the script (or BASEDIR):
  78 `ln -s /var/www/letsencrypt .acme-challenges`
  79
  80 ### dns-01 challenge
  81
  82 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.
  83
  84 You need a hook script that deploys the challenge to your DNS server!
  85
  86 ## Import
  87
  88 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).