Merge branch 'add-http-challenge' into 'master'

update docs

See merge request !32

docs/30_Usage.md

@@ -118,23 +118,101 @@ other ACTIONs
 
 ## CRUD actions for a certificate
 
+### Create (Issue)
+
 With parameter `add` you need to add all domains that should be included in a new certificate. 
 
 `[APPPATH]/cm.sh add     www.example.com mail.example.com`
 
+#### Mehtod: DNS auth
+
+By default the cert manager tries to use the DNS challenge
+
+`[APPPATH]/cm.sh add     www.example.com mail.example.com`
+
+In the configuration you need these variables:
+
+* CM_certmatch defines the domains that are allowed to use DNS auth.<br>to allow all: `export CM_certmatch="."`<br>To allow a specific subdomain: `export CM_certmatch="\.org\.example\.com"`
+* CM_challenge_alias is the domain you can manage via DNS api. <br>All hosts of this domain will be issued by a TXT record.<br>External domains need a CNAME. See <https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode>
+
+#### Mehtod: Http - using webroot
+
+If you have a http website of a domain you can authorize with a written challenge file. The file will be written below webroot.
+The SSL provider will make an http request `http://www.example.com/.well-known/acme-challenge/<generated-challenge-file>`
+
+The parameter --webroot is used to define the webroot of the existing web (without /.well-known/acme-challenge).
+
+Example:
+
+`[APPPATH]/cm.sh --webroot <webroot> add www.example.com mail.example.com`
+
+#### Mehtod: Http - using alias
+
+You can use an alias to place the generated challenge file outside webroot.
+The SSL provider will make an http request `http://www.example.com/.well-known/acme-challenge/<generated-challenge-file>` - this url must fit here too.
+
+(1) Create a .well-known directory
+
+Remark: this path is hardcoded :-/
+
+The directory is ../alias-dir/ - one directory outside the cm.sh.
+If your installation is in `/opt/letsencrypt/iml-certman/` then you need to create this directory: `/opt/letsencrypt/alias-dir/.well-known`
+
+(2) In Webserver enable mod_alias
+
+eg. on Debian /etc/apache2/mods-enabled/alias.load
+
+```
+LoadModule alias_module  /usr/lib/apache2/modules/mod_alias.so
+```
+
+(3) In Webserver create an alias pointing to your .well-known directory
+
+In your vhost (or global apache config) define an alias.
+
+```text
+Alias /.well-known "/opt/letsencrypt/alias-dir/.well-known"
+```
+
+If you have rewrite rules or proxy rules in the webroot keep in mind to have an exclude to allow file access on challenge files.
+
+```text
+RewriteEngine On
+RewriteCond %{REQUEST_URI} !^/.well-known
+RewriteRule ^(.*)$ index.php [QSA,L]
+```
+
+(4) Issue the cert
+
+use the parameter --alias without any value to create the challenge file in ../alias-dir/.
+
+Example:
+
+`[APPPATH]/cm.sh --alias add www.example.com mail.example.com`
+
 All other actions need the first domain only.
 
-The parameter **show** shows details.
+### Read
+
+Use the parameter **list** to show all certificates, aliases and dates.
+
+`[APPPATH]/cm.sh list`
+
+The parameter **show** shows details of a single certificate.
 
 `[APPPATH]/cm.sh show    www.example.com`
 
-If a certificate reaches the time for renewing (i.e. 4 weeks before expiration) you can renew it with **renew**. 
+### Update (renew)
+
+If a certificate reaches the time for renewing (i.e. 4 weeks before expiration) you can renew it with **renew**.
 
 Remark: if you try to renew before renewing date this results in a skip message (and exitcode 0).
 
 `[APPPATH]/cm.sh renew   www.example.com`
 
-With a delete command the certificate will be revoked and the local files will be deleted. 
+With a delete command the certificate will be revoked and the local files will be deleted.
+
+### Delete
 
 `[APPPATH]/cm.sh delete  www.example.com`
 
@@ -156,14 +234,6 @@ This ensure action handles the logic if a certificate must be
 
 It detects if a domain in the certificate can use a txt record or needs dns auth mode.
 
-## Show certificate data
-
-Use the listing `[APPPATH]/cm.sh list` or maybe filter it `[APPPATH]/cm.sh list | grep "mail."`
-
-to get a list of existing certs an then use the hostname in the 1st column to show details:
-
-`[APPPATH]/cm.sh show mail.example.com`
-
 ## Renew all certificates
 
 `[APPPATH]/cm.sh renew-all`