diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/03-Configuration.md | 104 |
1 files changed, 104 insertions, 0 deletions
diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md new file mode 100644 index 0000000..a70bf0b --- /dev/null +++ b/doc/03-Configuration.md @@ -0,0 +1,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. |