Commit 30573d33 authored by Hahn Axel (hahn)'s avatar Hahn Axel (hahn)
Browse files

update docs

parent 03a4e3c7
# 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
# 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.
......@@ -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
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment