rearranged documentation, added basic troubleshooting guide

README.md

@@ -14,13 +14,19 @@ Current features:
 - Renewal if a certificate is about to expire or SAN (subdomains) changed
 - Certificate revocation
 
-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).
-
-**Please note that you should use the staging URL when testing so as not to hit rate limits.** See the [Staging](#staging) section, below.
-
 Please keep in mind that this software and even the acme-protocol are relatively young and may still have some unresolved issues.
 Feel free to report any issues you find with this script or contribute by submitting a pullrequest.
 
+### Getting started
+
+For getting started I recommend taking a look at [docs/domains_txt.md](docs/domains_txt.md), [docs/wellknown.md](docs/wellknown.md) and the [Usage](#usage) section on this page (you'll probably only need the `-c` option).
+
+Generally you want to set up your WELLKNOWN path first, and then fill in domains.txt.
+
+**Please note that you should use the staging URL when experimenting with this script to not hit letsencrypts rate limits.** See [docs/staging.md](docs/staging.md).
+
+If you have any problems take a look at our [Troubleshooting](docs/troubleshooting.md) guide.
+
 ## Usage:
 
 ```text
@@ -45,79 +51,3 @@ Parameters:
  --challenge (-t) http-01|dns-01  Which challenge should be used? Currently http-01 and dns-01 are supported
  --algo (-a) rsa|prime256v1|secp384r1 Which public key algorithm should be used? Supported: rsa, prime256v1 and secp384r1
 ```
-
-### domains.txt
-
-The file `domains.txt` should have the following format:
-
-```text
-example.com www.example.com
-example.net www.example.net wiki.example.net
-```
-
-This states that there should be two certificates `example.com` and `example.net`,
-with the other domains in the corresponding line being their alternative names.
-
-### $WELLKNOWN / challenge-response
-
-Boulder (acme-server) is looking for challenge responses under your domain in the `.well-known/acme-challenge` directory
-
-This script uses `http-01`-type verification (for now) so you need to have that directory available over normal http (redirect to https will be acceptable).
-
-A full URL would look like `http://example.org/.well-known/acme-challenge/c3VjaC1jaGFsbGVuZ2UtbXVjaA-aW52YWxpZC13b3c`.
-
-An example setup to get this to work would be:
-
-nginx.conf:
-```
-...
-location /.well-known/acme-challenge {
-  alias /var/www/letsencrypt;
-}
-...
-```
-
-config.sh:
-```bash
-...
-WELLKNOWN="/var/www/letsencrypt"
-...
-```
-
-An alternative to setting the WELLKNOWN variable would be to create a symlink to the default location next to the script (or BASEDIR):
-`ln -s /var/www/letsencrypt .acme-challenges`
-
-### Staging
-
-Let’s Encrypt has stringent rate limits in place during the public beta period. If you start testing using the production endpoint (which is the default), you will quickly hit these limits and find yourself locked out. To avoid this, please set the CA property to the Let’s Encrypt staging server URL in your `config.sh` file:
-
-```bash
-CA="https://acme-staging.api.letsencrypt.org/directory"
-```
-
-### dns-01 challenge
-
-This script also supports the new `dns-01`-type verification. This type of verification requires you to be able to create a specific `TXT` DNS record for each hostname included in the certificate.
-
-You need a hook script that deploys the challenge to your DNS server!
-
-The hook script (indicated in the config.sh file or the --hook/-k command line argument) gets four arguments: an operation name (clean_challenge, deploy_challenge, or deploy_cert) and some operands for that. For deploy_challenge $2 is the domain name for which the certificate is required, $3 is a "challenge token" (which is not needed for dns-01), and $4 is a token which needs to be inserted in a TXT record for the domain.
-
-Typically, you will need to split the subdomain name in two, the subdomain name and the domain name separately. For example, for "my.example.com", you'll need "my" and "example.com" separately. You then have to prefix "_acme-challenge." before the subdomain name, as in "_acme-challenge.my" and set a TXT record for that on the domain (e.g. "example.com") which has the value supplied in $4
-
-```
-_acme-challenge    IN    TXT    $4
-_acme-challenge.my IN    TXT    $4
-```
-
-That could be done manually (as most providers don't have a DNS API), by having your hook script echo $1, $2 and $4 and then wait (read -s -r -e < /dev/tty) - give it a little time to get into their DNS system. Usually providers give you a boxes to put "_acme-challenge.my" and the token value in, and a dropdown to choose the record type, TXT. 
-
-Or when you do have a DNS API, pass the details accordingly to achieve the same thing.
-
-You can delete the TXT record when called with operation clean_challenge, when $2 is also the domain name.
-
-Here are some examples: [Examples for DNS-01 hooks](https://github.com/lukas2511/letsencrypt.sh/wiki/Examples-for-DNS-01-hooks)
-
-### Elliptic Curve Cryptography (ECC)
-
-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.

docs/dns-verification.md

+### dns-01 challenge
+
+This script also supports the new `dns-01`-type verification. This type of verification requires you to be able to create a specific `TXT` DNS record for each hostname included in the certificate.
+
+You need a hook script that deploys the challenge to your DNS server!
+
+The hook script (indicated in the config.sh file or the --hook/-k command line argument) gets four arguments: an operation name (clean_challenge, deploy_challenge, or deploy_cert) and some operands for that. For deploy_challenge $2 is the domain name for which the certificate is required, $3 is a "challenge token" (which is not needed for dns-01), and $4 is a token which needs to be inserted in a TXT record for the domain.
+
+Typically, you will need to split the subdomain name in two, the subdomain name and the domain name separately. For example, for "my.example.com", you'll need "my" and "example.com" separately. You then have to prefix "_acme-challenge." before the subdomain name, as in "_acme-challenge.my" and set a TXT record for that on the domain (e.g. "example.com") which has the value supplied in $4
+
+```
+_acme-challenge    IN    TXT    $4
+_acme-challenge.my IN    TXT    $4
+```
+
+That could be done manually (as most providers don't have a DNS API), by having your hook script echo $1, $2 and $4 and then wait (read -s -r -e < /dev/tty) - give it a little time to get into their DNS system. Usually providers give you a boxes to put "_acme-challenge.my" and the token value in, and a dropdown to choose the record type, TXT. 
+
+Or when you do have a DNS API, pass the details accordingly to achieve the same thing.
+
+You can delete the TXT record when called with operation clean_challenge, when $2 is also the domain name.
+
+Here are some examples: [Examples for DNS-01 hooks](https://github.com/lukas2511/letsencrypt.sh/wiki/Examples-for-DNS-01-hooks)

docs/domains_txt.md

+### domains.txt
+
+letsencrypt.sh uses the file `domains.txt` as configuration for which certificates should be requested.
+
+The file should have the following format:
+
+```text
+example.com www.example.com
+example.net www.example.net wiki.example.net
+```
+
+This states that there should be two certificates `example.com` and `example.net`,
+with the other domains in the corresponding line being their alternative names.

docs/ecc.md

+### Elliptic Curve Cryptography (ECC)
+
+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.

docs/import-from-official-client.md

+# Import
+
+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).

docs/staging.md

+# Staging
+
+Let’s Encrypt has stringent rate limits in place during the public beta period.
+
+If you start testing using the production endpoint (which is the default),
+you will quickly hit these limits and find yourself locked out.
+
+To avoid this, please set the CA property to the Let’s Encrypt staging server URL in your `config.sh` file:
+
+```bash
+CA="https://acme-staging.api.letsencrypt.org/directory"
+```
+
+Please keep in mind that at the time of writing this letsencrypt.sh doesn't have support for registration management,
+so if you change CA you'll have to move your `private_key.pem` (and, if you care, `private_key.json`) out of the way.

docs/troubleshooting.md

+# Troubleshooting
+
+Generally if the following information doesn't provide a solution to your problem please take a look at existing issues (search for keywords) before creating a new one.
+
+## "No registration exists matching provided key"
+
+You probably changed from staging-CA to production-CA (or the other way).
+
+Currently letsencrypt.sh doesn't detect a missing registration on the selected CA,
+the current workaround is to move `private_key.pem` (and, if you care, `private_key.json`) out of the way so the scripts generates and registers a new one.
+
+This will hopefully be fixed in the future.
+
+## "Error creating new cert :: Too many certificates already issued for: [...]"
+
+This is not an issue with letsencrypt.sh but an API limit with letsencrypt.
+
+At the time of writing this you can only create 5 certificates per domain in a sliding window of 7 days.
+
+## Invalid challenges
+
+There are a few factors that could result in invalid challenges.
+
+If you are using http validation make sure that the path you have configured with WELLKNOWN is readable under your domain.
+
+To test this create a file (e.g. `test.txt`) in that directory and try opening it with your browser: `http://example.org/.well-known/acme-challenge/test.txt`.
+
+If you get any error you'll have to fix your webserver configuration.

docs/wellknown.md

+# WELLKNOWN
+
+Let's Encrypt (or the ACME-protocol in general) is checking if you are in control of a domain by accessing a file under a path similar to `http://example.org/.well-known/acme-challenge/c3VjaC1jaGFsbGVuZ2UtbXVjaA-aW52YWxpZC13b3c`.
+
+`http-01`-type verification (default in this script, there is also support for [dns based verification](dns-verification.md)) so you need to have that directory available over normal http (redirect to https will be acceptable, but you definitively have to be able to access the http url!).
+
+letsencrypt.sh has a config variable called `WELLKNOWN`, which corresponds to the directory which should be served under `/.well-known/acme-challenge` on your domain.
+
+An example config would be to create a directory `/var/www/letsencrypt`, set `WELLKNOWN=/var/www/letsencrypt`.
+
+After configuration the WELLKNOWN directory you'll need to add an alias to your webserver configuration pointing to that path:
+
+## Nginx example config
+
+```nginx
+server {
+  [...]
+  location /.well-known/acme-challenge {
+    root /var/www/letsencrypt;
+  }
+  [...]
+}
+```
+
+## Apache example config
+
+```apache
+Alias /.well-known/acme-challenge /var/www/letsencrypt
+
+<Directory /var/www/letsencrypt>
+        Options None
+        AllowOverride None
+        Order allow,deny
+        Allow from all
+</Directory>
+```