doc: Initialize documentation

Both structure and huge parts are copied from Icinga DB and were altered
afterwards. The already existing Channel Plugin documentation was
extended.

config.example.yml

@@ -7,7 +7,7 @@
 #debug-password: "put-something-secret-here"
 
 icingaweb2-url: http://localhost/icingaweb2/
-channel-plugin-dir: /usr/libexec/icinga-notifications/channel
+channel-plugin-dir: /usr/libexec/icinga-notifications/channels
 
 database:
   type: pgsql

doc/01-About.md

@@ -0,0 +1,17 @@
+# Icinga Notifications
+
+Icinga Notifications is a set of components that processes received events from various sources, manages incidents and
+forwards notifications to predefined contacts, consisting of:
+
+* The Icinga Notifications daemon (this repository), which receives events and sends notifications
+* An [Icinga Web module](https://github.com/Icinga/icinga-notifications-web) that provides graphical configuration and further processing of the data collected by the daemon
+* And Icinga 2 and other custom sources that propagate state updates and acknowledgement events to the daemon
+
+## Installation
+
+To install Icinga Notifications see [Installation](02-Installation.md).
+
+## License
+
+Icinga Notifications and the Icinga Notifications documentation are licensed under the terms of the
+GNU General Public License Version 2.

doc/02-Installation.md

@@ -0,0 +1,125 @@
+<!-- {% if index %} -->
+# Installing Icinga Notifications
+
+The recommended way to install Icinga Notifications is to use prebuilt packages
+for all supported platforms from our official release repository.
+Please follow the steps listed for your target operating system,
+which guide you through setting up the repository and installing Icinga Notifications.
+
+To upgrade an existing Icinga Notifications installation to a newer version,
+see the [Upgrading](04-Upgrading.md) documentation for the necessary steps.
+
+Before installing Icinga Notifications, make sure you have installed [Icinga 2](https://icinga.com/docs/icinga-2)
+with the [`api` feature](https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/) configured and enabled.
+The Icinga 2 installation documentation covers all the necessary steps.
+
+<!-- {% else %} -->
+
+## Setting up the Database
+
+A MySQL (≥5.5), MariaDB (≥10.1), or PostgreSQL (≥9.6) database is required to run Icinga Notifications.
+Please follow the steps listed for your target database,
+which guide you through setting up the database and user and importing the schema.
+
+### Setting up a MySQL or MariaDB Database
+
+If you use a version of MySQL < 5.7 or MariaDB < 10.2, the following server options must be set:
+
+```
+innodb_file_format=barracuda
+innodb_file_per_table=1
+innodb_large_prefix=1
+```
+
+Set up a MySQL database for Icinga Notifications:
+
+```
+# mysql -u root -p
+
+CREATE DATABASE icinga-notifications;
+CREATE USER 'icinga-notifications'@'localhost' IDENTIFIED BY 'CHANGEME';
+GRANT ALL ON icinga-notifications.* TO 'icinga-notifications'@'localhost';
+```
+
+After creating the database, import the Icinga Notifications schema using the following command:
+
+```
+mysql -u root -p icinga-notifications </usr/share/icinga-notifications/schema/mysql/schema.sql
+```
+
+### Setting up a PostgreSQL Database
+
+Set up a PostgreSQL database for Icinga Notifications:
+
+```
+# su -l postgres
+
+createuser -P icinga-notifications
+createdb -E UTF8 --locale en_US.UTF-8 -T template0 -O icinga-notifications icinga-notifications
+psql icinga-notifications <<<'CREATE EXTENSION IF NOT EXISTS citext;'
+```
+
+The `CREATE EXTENSION` command requires the `postgresql-contrib` package.
+
+Edit `pg_hba.conf`, insert the following before everything else:
+
+```
+local all icinga-notifications           md5
+host  all icinga-notifications 0.0.0.0/0 md5
+host  all icinga-notifications      ::/0 md5
+```
+
+To apply these changes, run `systemctl reload postgresql`.
+
+After creating the database, import the Icinga Notifications schema using the following command:
+
+```
+psql -U icinga-notifications icinga-notifications < /usr/share/icinga-notifications/schema/pgsql/schema.sql
+```
+
+## Configuring Icinga Notifications
+
+Icinga Notifications installs its configuration file to `/etc/icinga-notifications/config.yml`,
+pre-populating most of the settings for a local setup. Before running Icinga Notifications,
+adjust the database credentials and, if necessary, the Icinga Web 2 URL.
+The configuration file explains general settings.
+All available settings can be found under [Configuration](03-Configuration.md).
+
+## Running Icinga Notifications
+
+The `icinga-notifications` package automatically installs the necessary systemd unit files to run Icinga Notifications.
+Please run the following command to enable and start its service:
+
+```bash
+systemctl enable --now icinga-notifications
+```
+
+## Installing Icinga Notifications Web
+
+With Icinga 2, Icinga Notifications and the database fully set up, it is now time to install Icinga Notifications Web,
+which connects to the database and allows configuring Icinga Notifications.
+
+The Icinga Notifications Web package is also included in the Icinga repository, and since it is already set up,
+you have completed the instructions here and can proceed to
+<!-- {% if amazon_linux %} -->
+[installing Icinga Notifications Web on Amazon Linux](https://icinga.com/docs/icinga-notifications-web/latest/doc/02-Installation/01-Amazon-Linux/#installing-icinga-notifications-web-package),
+<!-- {% endif %} -->
+<!-- {% if centos %} -->
+[installing Icinga Notifications Web on CentOS](https://icinga.com/docs/icinga-notifications-web/latest/doc/02-Installation/02-CentOS/#installing-icinga-notifications-web-package),
+<!-- {% endif %} -->
+<!-- {% if debian %} -->
+[installing Icinga Notifications Web on Debian](https://icinga.com/docs/icinga-notifications-web/latest/doc/02-Installation/03-Debian/#installing-icinga-notifications-web-package),
+<!-- {% endif %} -->
+<!-- {% if rhel %} -->
+[installing Icinga Notifications Web on RHEL](https://icinga.com/docs/icinga-notifications-web/latest/doc/02-Installation/04-RHEL/#installing-icinga-notifications-web-package),
+<!-- {% endif %} -->
+<!-- {% if sles %} -->
+[installing Icinga Notifications Web on SLES](https://icinga.com/docs/icinga-notifications-web/latest/doc/02-Installation/05-SLES/#installing-icinga-notifications-web-package),
+<!-- {% endif %} -->
+<!-- {% if ubuntu %} -->
+[installing Icinga Notifications Web on Ubuntu](https://icinga.com/docs/icinga-notifications-web/latest/doc/02-Installation/06-Ubuntu/#installing-icinga-notifications-web-package),
+<!-- {% endif %} -->
+which will also guide you through the setup of the Icinga Web PHP framework,
+which is required to run the Icinga Notifications web module.
+
+<!-- {% endif %} --><!-- {# end else if index #} -->

doc/02-Installation.md.d/From-Source.md

@@ -0,0 +1,20 @@
+# Installing Icinga Notifications from Source
+
+To install Icinga Notifications and get started, you first need to clone this repository.
+```bash
+git clone https://github.com/Icinga/icinga-notifications.git
+```
+
+Then, you can build both the daemon and all channels with the following commands.
+```bash
+go build -o icinga-notifications ./cmd/icinga-notifications-daemon
+go build -o /usr/libexec/icinga-notifications/channels ./cmd/channel/...
+```
+
+Finally, launch the daemon.
+```bash
+./icinga-notifications --config config.yml
+```
+
+<!-- {% set from_source = True %} -->
+<!-- {% include "02-Installation.md" %} -->

doc/03-Configuration.md

@@ -0,0 +1,115 @@
+# Configuration
+
+The configuration is stored in `/etc/icinga-notifications/config.yml`.
+See [config.example.yml](../config.example.yml) for an example configuration.
+
+Please note that this configuration file only contains the essentials.
+Detailed configuration as, i.e., the users, schedule, or channels, will be configured through Icinga Notifications Web.
+
+## Top Level Configuration
+
+### Listener Configuration
+
+The HTTP listener can be used both for submission and for debugging purposes.
+
+| Option         | Description                                                          |
+|----------------|----------------------------------------------------------------------|
+| listen         | Address to be bound to.                                              |
+| debug-password | Password expected via HTTP Basic Authentication for debug endpoints. |
+
+### Icinga Web 2
+
+The `icingaweb2-url` is expected to point to the base directory of your Icinga Web 2 installation,
+i.e., `https://example.com/icingaweb2/`, to be used for URL creation.
+
+### Channel Plugin Directory
+
+All available Icinga Notification Channel Plugins should resident in the `channel-plugin-dir`.
+For a package install, this directory should be `/usr/libexec/icinga-notifications/channels`.
+
+## Database Configuration
+
+Connection configuration for the database to which Icinga Notifications synchronizes monitoring data.
+This is also the database used in
+[Icinga Notifications Web](https://icinga.com/docs/icinga-notifications-web) to view and work with the data.
+
+| Option   | Description                                                                                                                                               |
+|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
+| type     | **Optional.** Either `mysql` (default) or `pgsql`.                                                                                                        |
+| host     | **Required.** Database host or absolute Unix socket path.                                                                                                 |
+| port     | **Optional.** Database port. By default, the MySQL or PostgreSQL port, depending on the database type.                                                    |
+| database | **Required.** Database name.                                                                                                                              |
+| user     | **Required.** Database username.                                                                                                                          |
+| password | **Optional.** Database password.                                                                                                                          |
+| tls      | **Optional.** Whether to use TLS.                                                                                                                         |
+| cert     | **Optional.** Path to TLS client certificate.                                                                                                             |
+| key      | **Optional.** Path to TLS private key.                                                                                                                    |
+| ca       | **Optional.** Path to TLS CA certificate.                                                                                                                 |
+| insecure | **Optional.** Whether not to verify the peer.                                                                                                             |
+| options  | **Optional.** List of low-level [database options](#database-options) that can be set to influence some Icinga Notifications internal default behaviours. |
+
+### Database Options
+
+Each of these configuration options are highly technical with thoroughly considered and tested default values that you
+should only change when you exactly know what you are doing. You can use these options to influence the Icinga Notifications default
+behaviour, how it interacts with databases, thus the defaults are usually sufficient for most users and do not need any
+manual adjustments.
+
+!!! important
+
+    Do not change the defaults if you do not have to!
+
+| Option                         | Description                                                                                                                                                 |
+|--------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| max_connections                | **Optional.** Maximum number of database connections Icinga Notifications is allowed to open in parallel if necessary. Defaults to `16`.                    |
+| max_connections_per_table      | **Optional.** Maximum number of queries Icinga Notifications is allowed to execute on a single table concurrently. Defaults to `8`.                         |
+| max_placeholders_per_statement | **Optional.** Maximum number of placeholders Icinga Notifications is allowed to use for a single SQL statement. Defaults to `8192`.                         |
+| max_rows_per_transaction       | **Optional.** Maximum number of rows Icinga Notifications is allowed to `SELECT`,`DELETE`,`UPDATE` or `INSERT` in a single transaction. Defaults to `8192`. |
+| wsrep_sync_wait                | **Optional.** Enforce [Galera cluster](#galera-cluster) nodes to perform strict cluster-wide causality checks. Defaults to `7`.                             |
+
+## Logging Configuration
+
+Configuration of the logging component used by Icinga Notifications.
+
+| Option   | Description                                                                                                                                                                                              |
+|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| level    | **Optional.** Specifies the default logging level. Can be set to `fatal`, `error`, `warn`, `info` or `debug`. Defaults to `info`.                                                                        |
+| output   | **Optional.** Configures the logging output. Can be set to `console` (stderr) or `systemd-journald`. If not set, logs to systemd-journald when running under systemd, otherwise stderr.                  |
+| interval | **Optional.** Interval for periodic logging defined as [duration string](#duration-string). Defaults to `"20s"`.                                                                                         |
+| options  | **Optional.** Map of component name to logging level in order to set a different logging level for each component instead of the default one. See [logging components](#logging-components) for details. |
+
+### Logging Components
+
+| Component       | Description                                                               |
+|-----------------|---------------------------------------------------------------------------|
+| channel         | Notification channels, their configuration and output.                    |
+| database        | Database connection status and queries.                                   |
+| icinga2         | Icinga 2 API communications, including the Event Stream.                  |
+| incident        | Incident management and changes.                                          |
+| listener        | HTTP listener for event submission and debugging.                         |
+| runtime-updates | Configuration changes through Icinga Notifications Web from the database. |
+
+## Appendix
+
+### Duration String
+
+A duration string is a sequence of decimal numbers and a unit suffix, such as `"20s"`.
+Valid units are `"ms"`, `"s"`, `"m"` and `"h"`.
+
+### Galera Cluster
+
+Icinga Notifications expects a more consistent behaviour from its database than a
+[Galera cluster](https://mariadb.com/kb/en/what-is-mariadb-galera-cluster/) provides by default. To accommodate this,
+Icinga Notifications sets the [wsrep_sync_wait](https://mariadb.com/kb/en/galera-cluster-system-variables/#wsrep_sync_wait) system
+variable for all its database connections. Consequently, strict cluster-wide causality checks are enforced before
+executing specific SQL queries, which are determined by the value set in the `wsrep_sync_wait` system variable.
+By default, Icinga Notifications sets this to `7`, which includes `READ, UPDATE, DELETE, INSERT, REPLACE` query types and is
+usually sufficient. Unfortunately, this also has the downside that every single Icinga Notifications query will be blocked until
+the cluster nodes resynchronise their states after each executed query, and may result in degraded performance.
+
+However, this does not necessarily have to be the case if, for instance, Icinga Notifications is only allowed to connect to a
+single cluster node at a time. This is the case when a load balancer does not randomly route connections to all the
+nodes evenly, but always to the same node until it fails, or if your database cluster nodes have a virtual IP address
+fail over assigned. In such situations, you can set the `wsrep_sync_wait` system variable to `0` in the 
+`/etc/icinga-notifications/config.yml` file to disable it entirely, as Icinga Notifications doesn't have to wait for cluster
+synchronisation then.

doc/04-Upgrading.md

@@ -0,0 +1,4 @@
+# Upgrading Icinga Notifications
+
+Specific version upgrades are described below. Please note that version upgrades are incremental.
+If you are upgrading across multiple versions, make sure to follow the steps for each of them.

doc/05-Distributed-Setups.md

@@ -0,0 +1 @@
+# Distributed Setups

doc/channel-plugin.md → doc/06-Channels.md

@@ -1,4 +1,20 @@
-## Channel Plugin
+# Channels
+
+After Icinga Notifications decides to send a notification of any kind, it will be passed to a channel plugin.
+Such a channel plugin submits the notification event to a channel, e.g., email or a chat client.
+
+Icinga Notifications comes packed with channel plugins, but also enables you to develop your own plugins.
+
+To make those plugins available to Icinga Notifications, they must be placed in the [plugin channel directory](03-Configuration.md#channel-plugin-directory).
+Afterwards they can be configured through Icinga Notifications Web.
+
+## Available Channels
+
+- _email_: Email submission via SMTP
+- _rocketchat_: Rocket.Chat
+- _webhook_: Configurable HTTP/HTTPS queries for your backend
+
+## Technical Channel Description
 
 Channel plugins are processes that run continuously and independently of each other. They receive many requests over
 their lifetime. They receive JSON-formatted requests on stdin and reply with JSON-formatted responses on stdout. The
@@ -73,4 +89,4 @@ Currently, the channel plugin include following three methods:
   [(example)](../internal/channel/examples/get-info.json)
 - `SendNotification`: Send the notifications. The `params` key should contain the information about the contact to be
   notified, corresponding object, the incident and the triggered event.
-  [(example)](../internal/channel/examples/send-notification.json)
+  [(example)](../internal/channel/examples/send-notification.json)