Adding upstream version 1:1.1.2.upstream/1%1.1.2upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.