From 067008c5f094ba9606daacbe540f6b929dc124ea Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 14 Apr 2024 15:31:28 +0200 Subject: Adding upstream version 1:1.3.2. Signed-off-by: Daniel Baumann --- doc/03-Configuration.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 doc/03-Configuration.md (limited to 'doc/03-Configuration.md') diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md new file mode 100644 index 0000000..4ecde77 --- /dev/null +++ b/doc/03-Configuration.md @@ -0,0 +1,77 @@ +# 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 +``` + +## Configure 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` + +Additionally, each job may also exclude specific **hosts** and **IP** addresses from scan. These hosts won't be scanned +when you run the [scan](04-Scanning.md#scan-command) or [jobs](04-Scanning.md#scheduling-jobs) command. Excluding an entire network and specifying IP addresses in CIDR +format will not work. You must specify concrete **IP**s and **host CN**s separated with commas, e.g: + +`192.0.2.2,192.0.2.5,icinga.com` + +### Job Schedules + +Schedules are [`cron`](https://crontab.guru) and rule based configs used to run jobs periodically at the given interval. +Every job is allowed to have multiple schedules that can be run independently of each other. Each job schedule provides +different options that you can use to control the scheduling behavior of the [jobs command](04-Scanning.md#scheduling-jobs). + +#### Examples + +A schedule that runs weekly on **Friday** and scans all targets that have not yet been scanned, or +whose last scan is older than `1 week`. + +![Weekly Schedules](res/weekly-schedules.png "Weekly Schedules") + +## 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. + +## Icinga Certificate Monitoring Daemon + +The default `systemd` service of this module, shipped with package installations, uses the [jobs command](04-Scanning.md#scheduling-jobs) +and runs all your configured jobs and schedules. + + + +> **Note** +> +> If you haven't installed this module from packages, you have to configure this as a `systemd` service yourself by just +> copying the example service definition from `/usr/share/icingaweb2/modules/x509/config/systemd/icinga-x509.service` +> to `/etc/systemd/system/icinga-x509.service`. + + +You can run the following command to enable and start the daemon. +``` +systemctl enable --now icinga-x509.service +``` -- cgit v1.2.3