30_Usage.md 5.29 KB
Newer Older
Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# Usage

## Selftest

Verify a new setup (or changes in the config) with `./cm.sh selftest`.

## Show help

Without any parameter it shows a help.

```text

./cm.sh 
_______________________________________________________________________________


                - - - ---===>>> CERT MANAGER <<<===--- - - -

_______________________________________________________________________________

DEBUG: Using Let's Encrypt STAGE environment ...
DEBUG: You can test and mess around. Do not use certs in production.

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
24

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
HELP

The basic syntax is
cm.sh [--trace] ACTION [FQDN] [ALIAS_1 [.. ALIAS_N]]

The ACTIONs for SINGLE certificate handlings are:

        add FQDN [.. FQDN-N] 
                create new certificate
                The first FQDN is a hostname to generate the certificate for. 
                Following multiple hostnames will be used as DNS aliases in the 
                same certificate.
                It updates files in ./certs

        ensure FQDN [.. FQDN-N] 
                It ensures that a certificate with given aliases exists and is up to date.
                This param is for simple usage in automation tools like Ansible or Puppet.
                It is required to add all aliases as parameters what is unhandy for
                direct usage on cli.

                If the cert does not exist it will be created (see "add").
                If fqdn and aliases are the same like in the certificate it performs a renew.
                If fqdn and aliases differ:
                - the current certificate will be rejected + deleted (see "delete")
                - a new certificate will be added ()

        delete FQDN
                delete all files of a given certificate

        renew FQDN
                renew (an already added) certificate
                and update files in ./certs

        show FQDN
Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
59
                show place of certificate data and show basic certificate data
Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
60
61
62
63
64
65
66
67
68
69
70
                (issuer, subject, aliases, ending date)

        transfer FQDN
                Transfer cert from acme.sh internal cache to our output dir again.
                It is done during add or renew. With transfer command you can repeat it.

ACTIONs for ALL certs

        list
                list all certificates including creation and renew date

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
71
72
73
74
75
76
77
        list-old
                list all certificates older 65 and older 90 days and exit.
                Exitcodes:
                  0 - all certs are up to date.
                  1 - certificates to renew were found
                  2 - outdatedt certificates were found

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
        renew-all
                renew all certificates (fast mode - without --force)
                and update files in ./certs
                It is useful for a cronjob.

other ACTIONs

        selftest
                check of health with current setup and requirements.
                This command is helpful for initial setups.

OPTIONS
        --trace (it must be the 1st parameter) 
                the output additionally will be written into a tracelog file 
                below ./log.

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
94

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
DEBUG: Using Let's Encrypt STAGE environment ...
DEBUG: You can test and mess around. Do not use certs in production.

```

## CRUD actions for a certificate

With parameter `add` you need to add all domains that should be included in a new certificate. 

`[APPPATH]/cm.sh add     www.example.com mail.example.com`

All other actions need the first domain only.

The parameter **show** shows details.

`[APPPATH]/cm.sh show    www.example.com`

If a certificate reaches the time for renewing (i.e. 4 weeks before expiration) you can renew it with **renew**. 

Remark: if you try to renew before renewing date this results in a skip message (and exitcode 0).

`[APPPATH]/cm.sh renew   www.example.com`

With a delete command the certificate will be revoked and the local files will be deleted. 

`[APPPATH]/cm.sh delete  www.example.com`

Then a certificate does not appear with cm.sh list anymore.

## The action "ensure"

In a scenario of automatic deployment with Ansible or Puppet you don't want to find out what action is needed: action add, remove old and add a new certificate or renew. The ensure action is a universal command to ensure somehow that the certificate exists, contains all DNS alt names and is up to date.

`[APPPATH]/cm.sh ensure www.example.com mail.example.com`

creates (or renews if close to expiriation) a certificate with 2 hostnames in it.

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
132
133
134
135
136
137
138
139
This ensure action 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.

Hahn Axel (hahn)'s avatar
Hahn Axel (hahn) committed
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
## Show certificate data

Use the listing `[APPPATH]/cm.sh list` or maybe filter it `[APPPATH]/cm.sh list | grep "mail."`

to get a list of existing certs an then use the hostname in the 1st column to show details:

`[APPPATH]/cm.sh show mail.example.com`

## Renew all certificates

`[APPPATH]/cm.sh renew-all`

## Logs

In **log/certmanager.log** you find a logging about time of changes for a certificate: when it was added, renewed, deleted. A skipped renew execution (even if it was triggered internally by "ensure") won't be logged.

Additionally there is a --trace option (must be the 1st param) - an execution output will be put to logfile that contains domain and timestamp.