blob: a70bf0bf540b4f5cd53f5e46bfcff5815f06ec3b (
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
|
# <a id="Configuration"></a>Configuration
## Importing CA certificates
The module tries to verify certificates using its own trust store. By default this trust store is empty and it
is up to the Icinga Web 2 admin to import CA certificates into it.
Using the `icingacli x509 import` command CA certificates can be imported. The certificate chain file that is specified
with the `--file` option should contain a PEM-encoded list of X.509 certificates which should be added to the trust
store:
```
icingacli x509 import --file /etc/ssl/certs/ca-certificates.crt
```
## Scan Jobs
The module needs to know which IP address ranges and ports to scan. These can be configured in
`Configuration -> Modules -> x509 -> Jobs`.
Scan jobs have a name which uniquely identifies them, e.g. `lan`. These names are used by the CLI command to start
scanning for specific jobs.
Each scan job can have one or more IP address ranges and one or more port ranges. The module scans each port in
a job's port ranges for all the individual IP addresses in the IP ranges.
IP address ranges have to be specified using the CIDR format. Multiple IP address ranges can be separated with commas,
e.g.:
`192.0.2.0/24,10.0.10.0/24`
Port ranges are separated with dashes (`-`). If you only want to scan a single port you don't need to specify the second
port:
`443,5665-5669`
Scan jobs can be executed using the `icingacli x509 scan` CLI command. The `--job` option is used to specify the scan
job which should be run:
```
icingacli x509 scan --job lan
```
## Scheduling Jobs
Each job may specify a `cron` compatible `schedule` to run periodically at the given interval. The `cron` format is as
follows:
```
* * * * *
- - - - -
| | | | |
| | | | |
| | | | +----- day of week (0 - 6) (Sunday to Saturday)
| | | +---------- month (1 - 12)
| | +--------------- day of month (1 - 31)
| +-------------------- hour (0 - 23)
+------------------------- minute (0 - 59)
```
Example definitions:
Description | Definition
------------------------------------------------------------| ----------
Run once a year at midnight of 1 January | 0 0 1 1 *
Run once a month at midnight of the first day of the month | 0 0 1 * *
Run once a week at midnight on Sunday morning | 0 0 * * 0
Run once a day at midnight | 0 0 * * *
Run once an hour at the beginning of the hour | 0 * * * *
Jobs are executed on CLI with the `jobs` command:
```
icingacli x509 jobs run
```
This command runs all jobs which are currently due and schedules the next execution of all jobs.
You may configure this command as `systemd` service. Just copy the example service definition from
`config/systemd/icinga-x509.service` to `/etc/systemd/system/icinga-x509.service` and enable it afterwards:
```
systemctl enable icinga-x509.service
```
As an alternative if you want scan jobs to be run periodically, you can use the `cron(8)` daemon to run them on a
schedule:
```
vi /etc/crontab
[...]
# Runs job 'lan' daily at 2:30 AM
30 2 * * * www-data icingacli x509 scan --job lan
```
## Server Name Indication
In case you are serving multiple virtual hosts under a single IP you can configure those in
`Configuration -> Modules -> x509 -> SNI`.
Each entry defines an IP with multiple hostnames associated with it. These are then utilized when jobs run.
Modules may also provide sources for SNI. At this time the module monitoring is the only one with known support.
|
