Skip to content
GitLab
Explore
Sign in
Primary navigation
Search or go to…
Project
C
certman
Manage
Activity
Members
Labels
Plan
Issues
Issue boards
Milestones
Wiki
Code
Merge requests
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Snippets
Build
Pipelines
Jobs
Pipeline schedules
Artifacts
Deploy
Releases
Container registry
Model registry
Operate
Environments
Monitor
Incidents
Analyze
Value stream analytics
Contributor analytics
CI/CD analytics
Repository analytics
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
Community forum
Contribute to GitLab
Provide feedback
Keyboard shortcuts
?
Snippets
Groups
Projects
Show more breadcrumbs
IML Open Source
certman
Commits
30573d33
Commit
30573d33
authored
3 years ago
by
Hahn Axel (hahn)
Browse files
Options
Downloads
Patches
Plain Diff
update docs
parent
03a4e3c7
No related branches found
No related tags found
1 merge request
!12
update docs
Changes
4
Hide whitespace changes
Inline
Side-by-side
Showing
4 changed files
docs/10_Installation.md
+0
-0
0 additions, 0 deletions
docs/10_Installation.md
docs/20_Configuration.md
+88
-0
88 additions, 0 deletions
docs/20_Configuration.md
docs/40_Certificate_files.md
+40
-0
40 additions, 0 deletions
docs/40_Certificate_files.md
docs/_index.md
+36
-1
36 additions, 1 deletion
docs/_index.md
with
164 additions
and
1 deletion
docs/
2
0_Installation.md
→
docs/
1
0_Installation.md
+
0
−
0
View file @
30573d33
File moved
This diff is collapsed.
Click to expand it.
docs/20_Configuration.md
0 → 100644
+
88
−
0
View file @
30573d33
# 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
This diff is collapsed.
Click to expand it.
docs/40_Certificate_files.md
0 → 100644
+
40
−
0
View file @
30573d33
# 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.
This diff is collapsed.
Click to expand it.
docs/_index.md
+
36
−
1
View file @
30573d33
...
...
@@ -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 certific
t
ae server are acme.sh and this wrapper. The wrapper has a parameter "ensure [FQDN]"
On the certifica
t
e 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
...
...
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment