_index.md 3.14 KB
Newer Older
Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
1
# IML certman
Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
2

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
3
Wrapper for **acme.sh** to create Let's Encrypt certificates using DNS authentication.
Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
4
5
It was written to create/ renew all needed certificates at a central system to deploy it from there (Ansible, Puppet, ...).

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
6
7
8
Source: <https://git-repo.iml.unibe.ch/open-source/iml-certman>

License: GNU GPL 3.0 <http://www.gnu.org/licenses/gpl-3.0.html>
Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
9
10
11
12
13
14
15

## Requirements

* bash
* openssl
* curl
* acme.sh client
Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
16
* dig (opional)
Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
17
18
19
20
21
22
23
24
25
26
27
28

## 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.

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
29
30
The focus is on handling certificates for domains with dns authentication or dns alias mode.

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
31
32
### Abstracted logic: parameter ensure

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
33
On the certificate server are acme.sh and this wrapper. The wrapper has a parameter "ensure [FQDN [FQDN N]]"
Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
34
35
36
37
38
39
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)

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
40
41
42
43
44
45
46
47
48
49
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.

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
50
51
52
53
54
55
56
### 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.

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
### 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
```

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
80
81
82
83
84
85
86
87
88
89
### 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.