update docs

docs/20_Configuration.md

+# Configuration default file
+
+Copy inc_config.sh.dist to inc_config.sh and make your settings.
+
+## Variables for DNS api access
+
+See https://github.com/acmesh-official/acme.sh/wiki/dnsapi
+
+* set the env vars of your dns provider
+* add provider in ACME_Params='--dns [PROVIDER]'
+
+```txt
+# -- for infoblox access 
+# export Infoblox_Creds='[user]:[Passwort]'
+# export Infoblox_Server='infoblox.localhost'
+# export ACME_Params='--dns dns_infoblox'
+```
+
+Note: you should use single quotes for credentials to prevent unwanted
+variable expansion.
+
+## Settings for wrapper cm.sh
+
+| variable           | type   | description                                                | value |
+|--------------------|--------|------------------------------------------------------------|-------|
+| ACME               | string | location of acme client; relative to cm.sh or as full path | ../acme.sh/acme.sh |
+| ACME_params        | string | parameters for acme client: dns, debugging, staging        |  |
+| CM_diracme         | string | location of certificate data; relative to cm.sh or as full path | ./certs |
+| CM_certmatch       | regex  | matcher to identify domains with dns access; all other domains will use dns alias mode | "\.example\.com" |
+| CM_challenge_alias | string | domain for validation with dns alias mode                  | "example.com" |
+| CM_user            | string | force a user to execute cm.sh                              | default: none (=any user can run cm.sh) |
+
+## inc_config.sh.dist
+
+```sh
+# ======================================================================
+#
+# add dns credentials and default params here
+#
+# ======================================================================
+
+
+# ----------------------------------------------------------------------
+# DNS API
+# see https://github.com/acmesh-official/acme.sh/wiki/dnsapi
+# - set the env vars of your dns provider
+# - add provider in ACME_Params='--dns [PROVIDER]'
+# ----------------------------------------------------------------------
+
+# -- for infoblox access 
+# export Infoblox_Creds='[user]:[Passwort]'
+# export Infoblox_Server='infoblox.localhost'
+# export ACME_Params='--dns dns_infoblox'
+
+
+# ----------------------------------------------------------------------
+# general settings
+# ----------------------------------------------------------------------
+
+# set path to acme.sh
+export ACME=../acme.sh/acme.sh
+
+# activate LE staging server for testing ... uncomment it for development
+# and testing purposes
+# export ACME_Params="$ACME_Params --staging"
+
+# activate debugging in acme.sh commands
+# export ACME_Params="$ACME_Params --debug"
+
+# where to write certificate data
+# export CM_diracme="./certs"
+
+# check domain names before creating a new certificate
+# It is used for faster rejection of a hostname or alias for which you
+# have no permission
+# export CM_certmatch="\.example\.com"
+
+# if a host is not matching CM_certmatch we will use authentication
+# with an alias domain
+# export CM_challenge_alias="example.com"
+
+# optional: force a user to execute cm.sh
+# this is for a central installation with a software deployment
+# like Ansible or puppet; default: none (=any user can run cm.sh)
+# export CM_user="ansible"
+
+# ----------------------------------------------------------------------
+```
\ No newline at end of file

docs/40_Certificate_files.md

+# Files of a Certificate
+
+
+The acme client recommends not to use the acme storage directly but to copy 
+the needed files into a wanted structure.
+
+After issue or renew a certificate with acme all files you need on the target system will be copied
+from acme to a certificate directory.
+
+## Target dir
+
+see ./inc_config.sh ... the target directory is set with
+
+```sh
+export CM_diracme="./certs"
+```
+
+## File structure
+
+The certificate folder contains the fqdn as directory and in it are the files:
+
+```txt
+./certs/
+  +-- www.example.com/
+      +-- www.example.com.ca.cer
+      +-- www.example.com.cert.cer
+      +-- www.example.com.fullchain.cer
+      +-- www.example.com.haproxy.pem
+      +-- www.example.com.key.pem
+```
+
+Here are the files from acme client
+
+* the key
+* the server certificate
+* the intermediate certificate
+* a chained certificate (server + intermediate certificate)
+* the ca certificate
+
+For Haproxy a 2nd chained certificate will be generated.

docs/_index.md

@@ -25,15 +25,27 @@ To deploy certicates as files each system must have the certificate file up to d
 server that keeps the certificates on a single place (the "master" for certificates). All machines
 trigger creation or update on that server and sync its files before deploying a certificate to a target.
 
+The focus is on handling certificates for domains with dns authentication or dns alias mode.
+
 ### Abstracted logic: parameter ensure
 
-On the certifictae server are acme.sh and this wrapper. The wrapper has a parameter "ensure [FQDN]"
+On the certificate server are acme.sh and this wrapper. The wrapper has a parameter "ensure [FQDN [FQDN N]]"
 that handles the logic if a certificate must be
 
 * created (if it does not exist) or
 * renewed (it already exists) or
 * re-created (the list of dns names in the certificate was changed)
 
+It detects if a domain in the certificate can use a txt record or needs dns auth mode.
+
+### Pre check with dig
+
+Accessing the API of Certificate provider can have limitations. Let's encrypt will block you
+after reaching the limit.
+
+To prevent making useless ssl requests for invalid hostnames that do not exist in dns they will be checked
+before starting the acme client.
+
 ### Handle parallel requests
 
 If you have multiple requests from different machines or parallel Ansible calls to deploy on multiple machines.
@@ -41,6 +53,29 @@ That we do not run into conflict that 2 running requests handle the same certifi
 a queuing mechanism. This allows just a 1 task to perform certificate actions. Other started
 scripts will wait until the earlier started script is finished.
 
+### Copy cert files
+
+After issue or renew a certificate with acme all files you need on the target system will be copied
+from acme to a certificate directory. That one contains the fqdn as directory and in it are
+
+* the key
+* the server certificate
+* the intermediate certificate
+* a chained certificate (server + intermediate certificate)
+* the ca certificate
+
+For Haproxy a 2nd chained certificate will be generated.
+
+```txt
+./certs/
+  +-- www.example.com/
+      +-- www.example.com.ca.cer
+      +-- www.example.com.cert.cer
+      +-- www.example.com.fullchain.cer
+      +-- www.example.com.haproxy.pem
+      +-- www.example.com.key.pem
+```
+
 ### Log creation/ renew/ delete
 
 The script writes a log that contains timestamp and domain of a certificate. On 100+ domains it is handy