diff --git a/docs/20_Installation.md b/docs/10_Installation.md similarity index 100% rename from docs/20_Installation.md rename to docs/10_Installation.md diff --git a/docs/20_Configuration.md b/docs/20_Configuration.md new file mode 100644 index 0000000000000000000000000000000000000000..8d46af566f76eaddf841875c29a377f9a55c6587 --- /dev/null +++ b/docs/20_Configuration.md @@ -0,0 +1,88 @@ +# 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 diff --git a/docs/40_Certificate_files.md b/docs/40_Certificate_files.md new file mode 100644 index 0000000000000000000000000000000000000000..9c22c1625a2dcd47a8a58ade99a773a62e4e1cfc --- /dev/null +++ b/docs/40_Certificate_files.md @@ -0,0 +1,40 @@ +# 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. diff --git a/docs/_index.md b/docs/_index.md index 46c18d9a23b6d5f8d7da3e09769da77408c96d31..e348829dc7cbb1d9d2c577187f595052dc3ed5d3 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -13,6 +13,7 @@ License: GNU GPL 3.0 <http://www.gnu.org/licenses/gpl-3.0.html> * openssl * curl * acme.sh client +* dig (opional) ## Why? @@ -25,15 +26,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 +54,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 diff --git a/inc_config.sh.dist b/inc_config.sh.dist index cf41e8a36c95e7dc3dffdda2ceca1096561f868b..c35fb2b3c28fd3b1753eb9057b03550a8b20e274 100644 --- a/inc_config.sh.dist +++ b/inc_config.sh.dist @@ -35,9 +35,6 @@ export ACME=../acme.sh/acme.sh # where to write certificate data # export CM_diracme="./certs" -# place for cnf + csr files -# export CM_dircsr="./csr" - # 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