From 8057a068851fd50688b630c518883c2a5a15bb3c Mon Sep 17 00:00:00 2001 From: Alvar Penning Date: Mon, 3 Jun 2024 09:53:35 +0200 Subject: [PATCH] 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 | 2 +- doc/01-About.md | 17 +++ doc/02-Installation.md | 125 ++++++++++++++++++++++ doc/02-Installation.md.d/From-Source.md | 20 ++++ doc/03-Configuration.md | 115 ++++++++++++++++++++ doc/04-Upgrading.md | 4 + doc/05-Distributed-Setups.md | 1 + doc/{channel-plugin.md => 06-Channels.md} | 20 +++- 8 files changed, 301 insertions(+), 3 deletions(-) create mode 100644 doc/01-About.md create mode 100644 doc/02-Installation.md create mode 100644 doc/02-Installation.md.d/From-Source.md create mode 100644 doc/03-Configuration.md create mode 100644 doc/04-Upgrading.md create mode 100644 doc/05-Distributed-Setups.md rename doc/{channel-plugin.md => 06-Channels.md} (73%) diff --git a/config.example.yml b/config.example.yml index 4877f16fd..d1cd064c4 100644 --- a/config.example.yml +++ b/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 diff --git a/doc/01-About.md b/doc/01-About.md new file mode 100644 index 000000000..ffb5d89c5 --- /dev/null +++ b/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. diff --git a/doc/02-Installation.md b/doc/02-Installation.md new file mode 100644 index 000000000..7aa99dcad --- /dev/null +++ b/doc/02-Installation.md @@ -0,0 +1,125 @@ + +# 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. + + + +## 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 +[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), + + +[installing Icinga Notifications Web on CentOS](https://icinga.com/docs/icinga-notifications-web/latest/doc/02-Installation/02-CentOS/#installing-icinga-notifications-web-package), + + +[installing Icinga Notifications Web on Debian](https://icinga.com/docs/icinga-notifications-web/latest/doc/02-Installation/03-Debian/#installing-icinga-notifications-web-package), + + +[installing Icinga Notifications Web on RHEL](https://icinga.com/docs/icinga-notifications-web/latest/doc/02-Installation/04-RHEL/#installing-icinga-notifications-web-package), + + +[installing Icinga Notifications Web on SLES](https://icinga.com/docs/icinga-notifications-web/latest/doc/02-Installation/05-SLES/#installing-icinga-notifications-web-package), + + +[installing Icinga Notifications Web on Ubuntu](https://icinga.com/docs/icinga-notifications-web/latest/doc/02-Installation/06-Ubuntu/#installing-icinga-notifications-web-package), + +which will also guide you through the setup of the Icinga Web PHP framework, +which is required to run the Icinga Notifications web module. + + diff --git a/doc/02-Installation.md.d/From-Source.md b/doc/02-Installation.md.d/From-Source.md new file mode 100644 index 000000000..2efccfd15 --- /dev/null +++ b/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 +``` + + + \ No newline at end of file diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md new file mode 100644 index 000000000..d7b97908c --- /dev/null +++ b/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. diff --git a/doc/04-Upgrading.md b/doc/04-Upgrading.md new file mode 100644 index 000000000..7df38a670 --- /dev/null +++ b/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. diff --git a/doc/05-Distributed-Setups.md b/doc/05-Distributed-Setups.md new file mode 100644 index 000000000..8167d7864 --- /dev/null +++ b/doc/05-Distributed-Setups.md @@ -0,0 +1 @@ +# Distributed Setups diff --git a/doc/channel-plugin.md b/doc/06-Channels.md similarity index 73% rename from doc/channel-plugin.md rename to doc/06-Channels.md index a40dec106..ead9821c0 100644 --- a/doc/channel-plugin.md +++ b/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) \ No newline at end of file + [(example)](../internal/channel/examples/send-notification.json)