-
Notifications
You must be signed in to change notification settings - Fork 41
/
Copy pathREADME.md
287 lines (234 loc) · 12.9 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
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
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
# certmgr
[](https://travis-ci.org/cloudflare/certmgr)
[](https://godoc.org/github.com/cloudflare/certmgr)
certmgr is a tool for managing certificates using CFSSL. It does the
following:
* Ensures certificates are present.
* Renews certificates before they expire.
* Triggering a service reload or restart on certificate updates.
It operates on **certificate specs**, which are JSON files containing
the information needed to generate a certificate.
At regular intervals, `certmgr` will check that the parameters set in a certificate spec match the PKI material on disk. `certmgr` will take actions as needed in ensuring and regenerating PKI material as needed. If there's an error, a material refresh will happen at a later time.
When run without any subcommands, certmgr will start monitoring
certificates. The configuration and specifications can be validated
using the `check` subcommand.
If you want to further understand the package logic, take a look at the [godocs](https://godoc.org/github.com/cloudflare/certmgr).
**Note**: `certmgr` requires Go 1.11 or later due to [cfssl](https://github.com/cloudflare/cfssl) dependency.
## Web server
When appropriately configured, `certmgr` will start a web server that
has the following endpoints:
* `/` just contains certmgr start time and current address.
* `/metrics` is the Prometheus endpoint (see the Metrics section).
## Metrics
Prometheus is used to collect some useful `certmgr` metrics. You can find them in the [godoc](https://godoc.org/github.com/cloudflare/certmgr/metrics).
## certmgr.yaml
The configuration file must be a YAML file; it is expected to be in
`/etc/certmgr/certmgr.yaml`. The location can be changed using the
`-f` flag.
An example `certmgr.yaml` file is:
```
dir: /etc/certmgr.d
default_remote: ca.example.net:8888
svcmgr: systemd
before: 72h
interval: 30m
metrics_port: 8080
metrics_address: localhost
```
This contains all of the currently available parameters:
* `dir`: this specifies the directory containing the certificate specs
* `svcmgr`: this specifies the service manager to use for restarting
or reloading services. This can be `systemd` (using `systemctl`),
`sysv` (using `service`), `circus` (using `circusctl`), `openrc` (using `rc-service`),
`dummy` (no restart/reload behavior), or `command` (see the command svcmgr section
for details of how to use this).
* `before`: optional: this is the default duration before a certificate expiry that certmgr starts attempting to
renew PKI. This defaults to 72 hours.
* `interval`: optional: this is the default for how often `certmgr` will check certificate expirations
and update PKI material on disk upon any changes (if necessary). This defaults to one hour.
* `interval_splay`: optional: this is used to vary the interval period. A random time between 0
and this value is added to `interval` if specified. This defaults to 0.
* `initial_splay`: if specified, a random sleep period between 0 and this value is used
for the initial sleep after startup of a spec. This provides a way to ensure that
if a fleet of certmgr are restarted at the same time, their period of wakeup is randomized
to avoid said fleet waking up and doing interval checks at the same time for a given spec.
This defaults to 0.
* `metrics_address`: specifies the address for the Prometheus HTTP
endpoint.
* `metrics_port`: specifies the port for the Prometheus HTTP endpoint.
* `take_actions_only_if_running`: boolean, if true, only fire a spec's action if the service is actually running.
If this is set to false (the default for historical reasons), this can lead to certmgr starting a downed service
when PKI expiry occurs.
## PKI Specs
A spec is used to manage PKI material for a consuming app. A spec does not have to request a certificate/key, and does not have to request a CA; it must request at least one of those two modes, however.
Said another way; you can use this to maintain a CA on disk. You can use this to maintain certificate/key pair signed by the given authority; you can do both modes if you wish, but one must be specified by the spec.
An example spec that writes both a CA and certificate key pair defined in JSON:
```
{
"service": "nginx",
"action": "restart",
"request": {
"CN": "www.example.net",
"hosts": [
"example.net",
"www.example.net"
],
"key": {
"algo": "ecdsa",
"size": 521
},
"names": [
{
"C": "US",
"ST": "CA",
"L": "San Francisco",
"O": "Example, LLC"
}
]
},
"private_key": {
"path": "/etc/ssl/private/www.key",
"owner": "www-data",
"group": "www-data",
"mode": "0600"
},
"certificate": {
"path": "/home/kyle/tmp/certmgr/certs/test1.pem",
"owner": "www-data",
"group": "www-data"
},
"ca": {
"path": "/etc/myservice/ca.pem",
"owner": "www-data",
"group": "www-data"
},
"authority": {
"remote": "ca.example.net:8888",
"auth_key": "012345678012345678",
"label": "www_ca",
"profile": "three-month",
"root_ca": "/etc/cfssl/api_server_ca.pem"
}
}
```
And this is an example that writes just the CA to disk:
```
{
"service": "nginx",
"action": "restart",
"authority": {
"remote": "ca.example.net:8888",
"auth_key": "012345678012345678",
"label": "www_ca",
"profile": "three-month",
"file": {
"path": "/etc/myservice/ca.pem",
"owner": "www-data",
"group": "www-data"
},
"root_ca": "/etc/cfssl/api_server_ca.pem"
}
}
```
A certificate spec has the following fields:
* `service`: this is optional, and names the service that the `action`
should be applied to.
* `action`: this is optional, and may be one of "restart", "reload",
or "nop".
* `svcmgr`: this is optional, and defaults to whatever the global
config defines. This allows fine-grained control for specifying the
svcmgr per cert. If you're using this in a raw certificate definition,
you likely want the 'command' svcmgr- see that section for details of
how to use it.
* `request`: a CFSSL certificate request (see below). If this is specified, a `certificate` and `private_key` field is required.
* `private_key` and `certificate`: file specifications (see below) for
the private key and certificate. Both must be specified- as must `request`- if you wish to manage a certificate/key pair.
* `authority`: contains the CFSSL CA configuration (see below).
* `before`: optional: this is the default duration before a certificate expiry that certmgr starts attempting to
renew PKI. This defaults to the managers default, which defaults to 72 hours if unspecified.
* `interval`: optional: this is the default for how often `certmgr` will check certificate expirations
and update PKI material on disk upon any changes (if necessary). This defaults to the managers default, which
defaults to one hour if unspecified.
* `interval_splay`: optional: this is used to vary the interval period. A random time between 0
and this value is added to `interval` if specified. This defaults to the managers default, which defaults to 0
if unspecified.
* `initial_splay`: if specified, a random sleep period between 0 and this value is used
for the initial sleep after startup of a spec. This provides a way to ensure that
if a fleet of certmgr are restarted at the same time, their period of wakeup is randomized
to avoid said fleet waking up and doing interval checks at the same time for a given spec.
This defaults to the managers default, which defaults to 0 if unspecified.
* `take_actions_only_if_running`: boolean, if true, only fire a spec's action if the service is actually running.
If this is set to false (the default for historical reasons), this can lead to certmgr starting a downed service
when PKI expiry occurs.
* `key_usages`: optional: An array of strings defining what this key should be used for. Certmgr will consider a cert invalid
if it does not contain these key usages. Possible values are from cfssl's [ExtKeyUsage map](https://github.com/cloudflare/cfssl/blob/1.3.3/config/config.go#L568)
**Note**: `certmgr` will throw a warning if `svcmgr` is `dummy` _AND_ `action` is "nop" or undefined. This is because such a setup will not properly restart or reload a service upon certificate renewal, which will likely cause your service to crash. Running `certmgr` with the `--strict` flag will not even load a certificate spec with a `dummy svcmgr` and undefined/nop `action` configuration.
File specifications contain the following fields:
* `path`: this is required, and is the path to store the file.
* `owner`: this is optional; if it's not provided, the current user is
used.
* `group`: this is optional; if it's not provided, the primary group
of the current user is used.
* `mode`: this is optional; if it's not provided, "0644" will be
used. It should be a numeric file mode.
CFSSL certificate requests have the following fields:
* `CN`: this contains the common name for the certificate.
* `hosts`: this is a list of SANs and/or IP addresses for the
certificate.
* `key`: this is optional; it should contain an "algo" of either "rsa"
or "ecdsa" and a "size" appropriate for the chosen
algorithm. Recommendations are "rsa" and 2048 or "ecdsa"
and 256. The default is "ecdsa" and 256.
* `names`: contains PKIX name information, including the "C"
(country), "ST" (state), "L" (locality/city), "O" (organisation),
and "OU" (organisational unit) fields.
The CA specification contains the following fields:
* `remote`: the CA to use. If not provided, the default remote from
the config file is used.
* `auth_key`: the authentication key used to request a certificate.
* `auth_key_file`: optional, if defined read the auth_key from this. If
`auth_key` and `auth_key_file` is defined, `auth_key` is used.
* `label`: the CA to use for the certificate.
* `profile`: the CA profile that should be used.
* `file`: if this is included, the CA certificate will be saved here. It
follows the same file specification format above. Use this if you want to save your CA cert to disk.
* `root_ca`: optionally, a path to a certificate to trust as CA for the
cfssl API server certificate. Usable if the "remote" is tls enabled
and configured with a self-signed certificate. By default,
the system root CA chain is trusted.
## `command svcmgr` and how to use it
If the svcmgr is set to `command`, then `action` is interpreted as a
shell snippet to invoke via `bash -c`. Bash is preferred since
it allows parse checks to run. If Bash isn't available, parse checks
are skipped and `sh -c` is used. If `sh` can't be found, then this svcmgr
is disabled. The `command svcmgr` is useful in Marathon environments.
Environment variables are set as follows:
* CERTMGR_CA_PATH: if CA was configured for the spec, this is the path
to the CA ondisk that was changed.
* CERTMGR_CERT_PATH: This is the path to the cert that was written.
* CERTMGR_KEY_PATH: This is the path to the key that was written.
## Subcommands
In addition to the certificate manager, there are a few utilities
functions specified:
* `check`: validates the configuration file and all the certificate
specs available in the certificate spec directory. Note that if you
wish to operate on just one spec, you can use `-d /path/to/that/spec`
to accomplish it.
* `clean`: removes all of the certificates and private keys specified
by the certificate specs. Note that if you wish to operate on just one spec,
you can use `-d /path/to/that/spec` to accomplish it.
* `ensure`: attempts to load all certificate specs, and ensure that
the TLS key pairs they identify exist, are valid, and that they are
up-to-date. Note that if you wish to operate on just one spec, you
can use `-d /path/to/that/spec` to accomplish this.
* `genconfig`: generates a default configuration file and ensures the
default service directory exists.
* `version`: prints certificate manager's version, the version of Go
it was built with, and shows the current configuration.
## See also
The `certmgr` spec is included as `SPEC.rst`.
## Contributing
To contribute, fork this repo and make your changes. Then, make a PR to this repo. A PR requires at least one approval from a repo admin and successful CI build.
### Unit Testing
Unit tests can be written locally. This should be straightforward in a Linux environment.
To run them in a non-Linux environment, have Docker up and run `make test`. This will spin up a container with your local build. From here you can `go test -v ./...` your files. This unconventional setup is because [cfssl](https://github.com/cloudflare/cfssl), the underlying logic of `certmgr`, uses [cgo](https://golang.org/cmd/cgo/).