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.