diff --git a/README.md b/README.md index a69523db..ccea34b9 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,58 @@ # Icinga Notifications Web -> **Warning** -> -> This is an early preview version for you to try, but do not use this in production. There may still be severe bugs -> and incompatible changes may happen without any notice. At the moment, we don't provide any support for this. +[![PHP Support](https://img.shields.io/badge/php-%3E%3D%207.2-777BB4?logo=PHP)](https://php.net/) +![Build Status](https://github.com/Icinga/icinga-notifications-web/actions/workflows/php.yml/badge.svg?branch=main) +[![Github Tag](https://img.shields.io/github/tag/Icinga/icinga-notifications-web.svg)](https://github.com/Icinga/icinga-notifications-web/releases/latest) + +> [!WARNING] +> This is an early beta version for you to try, but do not use this in production. There may still be severe bugs. +> +> At the moment, we don't provide any support for this module. 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](https://github.com/Icinga/icinga-notifications), which receives events and sends notifications -* An Icinga Web module (this repository), 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 +* [Icinga Notifications](https://github.com/Icinga/icinga-notifications), which receives events and sends notifications. +* Icinga Notifications Web, which provides graphical configuration. + +Icinga 2 itself and miscellaneous other sources propagate state updates and other events to [Icinga Notifications](https://github.com/Icinga/icinga-notifications). + +## Big Picture + +![Icinga Notifications Architecture](doc/res/notifications-architecture.png) + +Because Icinga Notifications consists of several components, +this section tries to help understand how these components relate. + +First, the Icinga Notifications configuration resides in a SQL database. +It can be conveniently tweaked via Icinga Notifications Web directly from a web browser. +The Icinga Notifications daemon uses this database to read the current configuration. -## Installation +As in any Icinga setup, all host and service checks are defined in Icinga 2. +By querying the Icinga 2 API, the Icinga Notifications daemon retrieves state changes, acknowledgements and other events. +These events are stored in the database and are available for further inspection in Icinga Notifications Web. +Next to Icinga 2, other notification sources can be configured. -First, install the [daemon](https://github.com/Icinga/icinga-notifications). +Depending on its configuration, the daemon will take action on these events. +This optionally includes escalations that are sent through a channel plugin. +Each of those channel plugins implements a domain-specific transport, e.g., the `email` channel sends emails via SMTP. +When configured, Icinga Notifications will use channel plugins to notify end users or talk to other APIs. -Then install this like any other [module](https://icinga.com/docs/icinga-web/latest/doc/08-Modules/). Use `notifications` as name. +## Available Channels -## Configuration +Icinga Notifications comes with multiple channels out of the box: -After you have enabled the module, create a new database resource pointing to the database you have created -during the installation process of the daemon. Then choose it as the backend for the module at: -`Configuration -> Modules -> notifications -> Database (Tab)` +* _email_: Email submission via SMTP +* _rocketchat_: Rocket.Chat +* _webhook_: Configurable HTTP/HTTPS queries for third-party backends -Your next step should be to set up the channels you want to use to send notifications over. You do this at: -`Configuration -> Modules -> notifications -> Channels (Tab)`. +Additional custom channels can be developed independently of Icinga Notifications, +following the [channel specification](https://icinga.com/docs/icinga-notifications/latest/doc/10-Channels). -> **Note** -> -> Make sure the **daemon** is able to connect to the SMTP host or Rocket.Chat Instance! +## Documentation -The base configuration is now done. You can continue now by setting up your first contacts, event rules and schedules! -You do this at: `Notifications -> Configuration` +Icinga Notifications Web documentation is available at [icinga.com/docs](https://icinga.com/docs/icinga-notifications-web/latest). ## License -Icinga Notifications is licensed under the terms of the [GNU General Public License Version 2](LICENSE). +Icinga Notifications Web and its documentation are licensed under the terms of the [GNU General Public License Version 2](LICENSE). diff --git a/doc/01-About.md b/doc/01-About.md new file mode 100644 index 00000000..7217bd0a --- /dev/null +++ b/doc/01-About.md @@ -0,0 +1,55 @@ +# Icinga Notifications Web + +!!! warning + + This is an early beta version for you to try, but do not use this in production. There may still be severe bugs. + + At the moment, we don't provide any support for this module. + +Icinga Notifications is a set of components that processes received events from miscellaneous sources, manages +incidents and forwards notifications to predefined contacts, consisting of: + +* [Icinga Notifications](https://github.com/Icinga/icinga-notifications), which receives events and sends notifications. +* Icinga Notifications Web, which provides graphical configuration. + +Icinga 2 itself and other sources propagate state updates and other events to [Icinga Notifications](https://github.com/Icinga/icinga-notifications). + +## Big Picture + +![Icinga Notifications Architecture](res/notifications-architecture.png) + +Because Icinga Notifications consists of several components, +this section tries to help understand how these components relate. + +First, the Icinga Notifications configuration resides in a SQL database. +It can be conveniently tweaked via Icinga Notifications Web directly from a web browser. +The Icinga Notifications daemon uses this database to read the current configuration. + +As in any Icinga setup, all host and service checks are defined in Icinga 2. +By querying the Icinga 2 API, the Icinga Notifications daemon retrieves state changes, acknowledgements and other events. +These events are stored in the database and are available for further inspection in Icinga Notifications Web. +Next to Icinga 2, other notification sources can be configured. + +Depending on its configuration, the daemon will take action on these events. +This optionally includes escalations that are sent through a channel plugin. +Each of those channel plugins implements a domain-specific transport, e.g., the `email` channel sends emails via SMTP. +When configured, Icinga Notifications will use channel plugins to notify end users or talk to other APIs. + +## Available Channels + +Icinga Notifications comes with multiple channels out of the box: + +* _email_: Email submission via SMTP +* _rocketchat_: Rocket.Chat +* _webhook_: Configurable HTTP/HTTPS queries for third-party backends + +Additional custom channels can be developed independently of Icinga Notifications, +following the [channel specification](https://icinga.com/docs/icinga-notifications/latest/doc/10-Channels). + +## Installation + +To install Icinga Notifications Web see [Installation](02-Installation.md). + +## License + +Icinga Notifications Web and its documentation are licensed under the terms of the [GNU General Public License Version 2](https://github.com/Icinga/icinga-notifications-web?tab=GPL-2.0-1-ov-file#readme). diff --git a/doc/02-Installation.md b/doc/02-Installation.md new file mode 100644 index 00000000..193a1107 --- /dev/null +++ b/doc/02-Installation.md @@ -0,0 +1,26 @@ + + +# Installing Icinga Notifications Web + +The recommended way to install Icinga Notifications Web 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 Web. + +Before installing Icinga Notifications Web, make sure you have installed +[Icinga Notifications](https://icinga.com/docs/icinga-notifications/latest/doc/02-Installation). + + + + + +## Installing the Package + +If the [repository](https://packages.icinga.com) is not configured yet, please add it first. +Then use your distribution's package manager to install the `icinga-notifications-web` package +or install [from source](02-Installation.md.d/From-Source.md). + + +This concludes the installation. Now proceed with the [configuration](03-Configuration.md). + 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 00000000..9b80d5a1 --- /dev/null +++ b/doc/02-Installation.md.d/From-Source.md @@ -0,0 +1,19 @@ +# Installing Icinga Notifications Web from Source + +Please see the Icinga Web documentation on +[how to install modules](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation) from source. +Make sure you use `notifications` as the module name. The following requirements must also be met. + +### Requirements + +- PHP (≥7.2) +- PHP needs the following extensions to be installed and activated: + - `json` +- [MySQL](https://www.php.net/manual/en/ref.pdo-mysql.php) + or [PostgreSQL](https://www.php.net/manual/en/ref.pdo-pgsql.php) PDO PHP libraries +- [Icinga Notifications](https://github.com/Icinga/icinga-notifications) +- [Icinga Web](https://github.com/Icinga/icingaweb2) (≥2.9) +- [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (≥0.12.0) +- [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (≥0.11.0) + + diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md new file mode 100644 index 00000000..2059a1f6 --- /dev/null +++ b/doc/03-Configuration.md @@ -0,0 +1,72 @@ +# Configuration + +![Icinga Notifications Web Preview](res/notifications-preview.png) + +If Icinga Web has been installed but not yet set up, please visit Icinga Web and follow the web-based setup wizard. +For Icinga Web setups already running, log in to Icinga Web with a privileged user and follow the steps below to +configure Icinga Notifications Web: + + + +## Module Activation + +If you just installed the module, do not forget to activate it on your Icinga Web instance(s) by using your +preferred way: + +- Use Icinga Web's command-line interface on the webserver(s) and execute `icingacli module enable notifications`. +- Visit Icinga Web, log in as a privileged user and activate the module under `Configuration → + Modules → notifications` by switching the state from `disabled` to `enabled`. + + + +## Database Configuration + +Connection configuration for the database, which both, +[Icinga Notifications](https://github.com/Icinga/icinga-notifications) and [Icinga Notifications Web](https://github.com/Icinga/icinga-notifications-web), use. + +!!! tip + + If not already done, initialize your database by following the [instructions](https://icinga.com/docs/icinga-notifications/latest/doc/02-Installation#setting-up-the-database). + +1. Create a new resource for the Icinga Notifications database via the `Configuration → Application → Resources` menu. +2. Configure the resource you just created as the database connection for the Icinga Notifications Web module using the + `Configuration → Modules → notifications → Database` menu. + +## Channels Configuration + +As the Icinga Notifications daemon notifies contacts in case of events and incidents, you need to configure appropriate +communication channels. + +The currently supported channels can be found [here](01-About.md#available-channels). + +They can be configured through `Configuration → Modules → notifications → Channels` and the credentials to be supplied +might differ depending on the channel type. + +You need to configure at least one valid communication channel to be able to supply your contacts with notifications. + +## Sources Configuration + +The notifications module operates on data fed by miscellaneous sources and is therefore not restricted to Icinga 2 only. +Consult the source specific documentation on how to integrate such. + +You need to provide at least one valid source for this module to function properly. + +### Adding an Icinga 2 source + +!!! tip + + If there is no API user with the required permissions yet, read through [Icinga's API documentation](https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#authentication). + + The API user needs the following [permissions](https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#overview): + + - `events/*` + + - `objects/query/*` + +If you want the notifications module to process Icinga 2 events, you will need to add it as a source: + +1. Navigate to `Configuration → Module → notifications → Sources` and add a new source. +2. Choose type `Icinga` and provide the Icinga 2 API credentials. +3. (Optional) Disable `Verify API Certificate` if you want + [Icinga Notifications](https://icinga.com/docs/icinga-notifications/latest) to skip its check for the certificate + validity of the given REST API endpoint. diff --git a/doc/06-Desktop-Notifications.md b/doc/06-Desktop-Notifications.md index f93924eb..60a4fe0c 100644 --- a/doc/06-Desktop-Notifications.md +++ b/doc/06-Desktop-Notifications.md @@ -3,10 +3,11 @@ With Icinga Notifications, users are able to enable desktop notifications which will inform them about severity changes in incidents they are notified about. -> **Note** -> -> This feature is currently considered experimental and might not work as expected in all cases. -> We will continue to improve this feature in the future. Your feedback is highly appreciated. +!!! Note + + This feature is currently considered experimental and might not work as expected in all cases. + + We will continue to improve this feature in the future. Your feedback is highly appreciated. ## How It Works @@ -81,11 +82,12 @@ location ~ ^/icingaweb2/notifications/v(\d+)/subscribe$ { } ``` -> **Note** -> -> Since these connections are long-lived, the default web server configuration might impose a too small limit on -> the maximum number of connections. Make sure to adjust this limit to a higher value. If working correctly, the -> daemon will limit the number of connections per client to 2. +!!! Note + + Since these connections are long-lived, the default web server configuration might impose a too small limit on + the maximum number of connections. Make sure to adjust this limit to a higher value. + + If working correctly, the daemon will limit the number of connections per client to 2. ### Enable The Daemon @@ -93,11 +95,12 @@ The default `systemd` service, shipped with package installations, runs the back -> **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/notifications/config/systemd/icinga-desktop-notifications.service` -> to `/etc/systemd/system/icinga-desktop-notifications.service`. +!!! 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/notifications/config/systemd/icinga-desktop-notifications.service` + to `/etc/systemd/system/icinga-desktop-notifications.service`. + You can run the following command to enable and start the daemon. diff --git a/doc/res/notifications-architecture.png b/doc/res/notifications-architecture.png new file mode 100644 index 00000000..adb43e4a Binary files /dev/null and b/doc/res/notifications-architecture.png differ diff --git a/doc/res/notifications-preview.png b/doc/res/notifications-preview.png new file mode 100644 index 00000000..cd9f464e Binary files /dev/null and b/doc/res/notifications-preview.png differ