blob: 7ef3abd27cb865babd00229bc32074383d15dc26 (
plain)
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
|
# <a id="Monitoring"></a>Monitoring
## Host Check Command
The module provides a CLI command to check a host's certificate. It does so by
fetching all the necessary information from this module's own database.
### Usage
General: `icingacli x509 check host [options]`
Options:
```
--ip A hosts IP address
--host A hosts name
--port The port to check in particular
--warning Less remaining time results in state WARNING [25%]
--critical Less remaining time results in state CRITICAL [10%]
--allow-self-signed Ignore if a certificate or its issuer has been self-signed
```
### Threshold Definition
Thresholds can either be defined relative (in percent) or absolute (time interval).
Time intervals consist of a digit and an accompanying unit (e.g. "3M" are three
months). Supported units are:
Identifier | Description
------------|------------
y, Y | Year
M | Month
d, D | Day
h, H | Hour
m | Minute
s, S | Second
**Example:**
```
$ icingacli x509 check host --host example.org --warning 1y
WARNING - *.example.org expires in 219 days|'*.example.org'=18985010s;25574400;10281600;0;102470399
```
### Performance Data
The command outputs a performance data value for each certificate that is
served by the host. The value measured is the amount of seconds remaining
until the certificate expires.
The value of `max` is the total amount of seconds the certificate is valid.
`warning` and `critical` are the seconds remaining after which the respective
state is reported.
## Icinga 2 Integration
First off, this chapter relies on the fact that you're using the Director
already and that you're familiar with some of the terms and functionalities
used there.
If you don't want to use the Director, know that Icinga 2 already provides
an appropriate template for the host check command in its template library:
https://icinga.com/docs/icinga2/latest/doc/10-icinga-template-library/#x509
### Director Import Sources
The module provides two different import sources:
#### Hosts (X509)
Focuses on the hosts the module found when scanning the networks. Use this
for the most straightforward way of integrating the results into your
environment. It's also the utilized source in the example further below.
Columns provided by this source:
Name | Description
----------------|--------------------------------------------------------------
host_name_or_ip | Default key column. This is primarily `host_name`, though if this is not unique it falls back to `host_ip` for individual results
host_ip | A host's IP address by which it is known to this module. May be IPv4 or IPv6
host_name | A host's name as detected by SNI or a reverse DNS lookup during the scan process
host_ports | Separated by comma. All ports where certificates were found
host_address | Set to `host_ip` if it is IPv4 else `null`
host_address6 | Set to `host_ip` if it is IPv6 else `null`
#### Services (X509)
While the hosts import source does not provide any details about the found
certificates this one does. This also means that this source may generate
multiple results for a single host since it focuses on the found certificates.
Use this source if you want to import service objects directly and relate them
to already existing hosts by their utilized certificates. The Director's many
utilities provided in this regard will again come in handy here.
Columns provided by this source:
Name | Description
----------------------|--------------------------------------------------------
host_name_ip_and_port | Default key column. This is a combination of `host_name`, `host_ip` and `host_port` in the format `name/ip:port`
host_ip | A host's IP address by which it is known to this module. May be IPv4 or IPv6
host_name | A host's name as detected by SNI or a reverse DNS lookup during the scan process
host_port | A host's port where a certificate has been found
host_address | Set to `host_ip` if it is IPv4 else `null`
host_address6 | Set to `host_ip` if it is IPv6 else `null`
cert_subject | A certificate's common name
cert_issuer | The issuer's common name
cert_self_signed | Whether the certificate is self-signed (`yes` or `no`)
cert_trusted | Whether the certificate is trusted (`yes` or `no`)
cert_valid_from | The certificate's start time of validity (UNIX timestamp)
cert_valid_to | The certificate's end time of validity (UNIX timestamp)
cert_fingerprint | The certificate's fingerprint (hex-encoded)
cert_dn | The certificate's distinguished name
cert_subject_alt_name | The certificate's alternative subject names (Comma separated pairs of `type:name`)
### Service Checks With the Hosts Import Source
This example covers the setup of service checks by using a particular host
template and suggests then two options utilizing service apply rules.
#### Preparations
Assuming the check command definition `icingacli-x509` has already been imported
you need to define a few data fields now:
Field name | Data type
---------------------------------|----------
certified_ports | Array
icingacli_x509_ip | String
icingacli_x509_host | String
icingacli_x509_port | String
icingacli_x509_warning | String
icingacli_x509_critical | String
icingacli_x509_allow_self_signed | Boolean
Then please create a new host template with a name of your choosing. We've chosen
`x509-host`. We're also importing our base template `base-host` here which defines
all the default properties of our hosts.
This host template also requires three data fields which are shown below.
A service template is also needed. We chose the name `x509-host-check` and
`icingacli-x509` as check command.
The service template now requires all data fields which correspond to the
check command's parameters.
#### Import Source Setup
Create a new import source of type `Hosts (X509)`.
Configure a property modifier for column `host_ports` of type `Split` and use
the comma `,` as delimiter.
The preview should now produce a similar result to this:
#### Sync Rule Setup
Create a new sync rule for objects of type `Host`. Depending on your environment
you may choose either `Merge` or `Replace` as update policy. Choose `Merge` to
continue with this example.
Which properties this rule defines is also very dependent on what you want to
achieve. We now assume that you already have host objects whose object names
match exactly those the import source provides. (Hence you should choose
`Merge` as update policy)
#### Service Check Setup
There are two choices now. The first checks a host's certificates as a single
service. The second creates for each individual certificate (port) a service.
##### Single Service
This is done by defining a new service as part of the host template created
earlier. There add a service and choose the service template also created
previously.
Once you've triggered the import and synchronisation as well as deployed
the resulting changes you should see this in Icinga Web 2:
##### Multiple Services
This utilizes a service apply rule. Trigger the import and synchronisation
first, otherwise you can't choose a custom variable for the *apply for* rule.
Once the synchronisation is finished, set up the service apply rule like this:
After deploying the resulting changes you should see this in Icinga Web 2:
|
