Merge branch '5213-handle-dns-alias-domain' into 'master'

update doc

See merge request open-source/iml-certman!11

docs/_index.md

@@ -13,3 +13,41 @@ License: GNU GPL 3.0 <http://www.gnu.org/licenses/gpl-3.0.html>
 * openssl
 * curl
 * acme.sh client
+
+## Why?
+
+The acme script allows basic actions for certificates.
+
+### Central certificate server
+
+We use Ansible on several local instances - on the machines of sysadmins and an AWX instance for scheduling tasks.
+To deploy certicates as files each system must have the certificate file up to date. Here we use a
+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.
+
+### Abstracted logic: parameter ensure
+
+On the certifictae server are acme.sh and this wrapper. The wrapper has a parameter "ensure [FQDN]"
+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)
+
+### Handle parallel requests
+
+If you have multiple requests from different machines or parallel Ansible calls to deploy on multiple machines.
+That we do not run into conflict that 2 running requests handle the same certificate there is
+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.
+
+### Log creation/ renew/ delete
+
+The script writes a log that contains timestamp and domain of a certificate. On 100+ domains it is handy
+to verify when what was done what for a given domain.
+
+### List old certificates
+
+Automation is wonderful. You create systems and certificates for them on the fly.
+And you destroy test machines. A parameter "list-old" shows certiciates that were not renewed
+anymore and are older 90 days.