Skip to content

Commit d3001e8

Browse files
oxzijulianbrost
oxzi
authored and
julianbrost
committed
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.
1 parent 32bf26e commit d3001e8

13 files changed

+444
-35
lines changed

‎Makefile

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# These variables follow the naming convention from the GNU Make documentation
22
# but their defaults correspond to the rest of the code (note that changing
33
# libexecdir here wouldn't affect the default path for the channel plugin
4-
# directory used by the dameon for example).
4+
# directory used by the daemon for example).
55
#
66
# https://www.gnu.org/software/make/manual/html_node/Directory-Variables.html
77
prefix ?= /usr

‎README.md

+14-29
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,26 @@
11
# Icinga Notifications
22

3-
> **Warning**
4-
> This is an early preview version for you to try, but do not use this in production. There may still be severe bugs
5-
> and incompatible changes may happen without any notice. At the moment, we don't yet provide any support for this.
3+
> [!WARNING]
4+
> This is an early preview version for you to try, but do not use this in production.
5+
> There may still be severe bugs and incompatible changes may happen without any notice.
6+
> At the moment, we don't yet provide any support for this.
67
78
Icinga Notifications is a set of components that processes received events from various sources, manages incidents and
89
forwards notifications to predefined contacts, consisting of:
910

10-
* The Icinga Notifications daemon (this repository), which receives events and sends notifications
11-
* 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
12-
* And Icinga 2 and other custom sources that propagate state updates and acknowledgement events to the daemon
11+
* The Icinga Notifications daemon (this repository), which receives events and sends notifications.
12+
* The [Icinga Notifications Web](https://github.com/Icinga/icinga-notifications-web) module,
13+
which provides graphical configuration.
14+
* Icinga 2 and other sources that provide monitoring events that result in notifications.
1315

14-
## Installation
16+
![Icinga Notifications Architecture](doc/images/icinga-notifications-architecture.png)
1517

16-
To install Icinga Notifications and get started, you first need to clone this repository.
17-
```bash
18-
git clone https://github.com/Icinga/icinga-notifications.git
19-
```
18+
## Documentation
2019

21-
Next, you need to provide a `config.yml` file, similar to the [example config](config.example.yml), for the daemon.
22-
It is required that you have created a new database and imported the [schema](schema/pgsql/schema.sql) file beforehand.
23-
> **Note**
24-
> At the moment **PostgreSQL** is the only database backend we support.
25-
26-
Additionally, it also requires you to manually insert items into the **source** table before starting the daemon.
27-
```sql
28-
INSERT INTO source
29-
(id, type, name, icinga2_base_url, icinga2_auth_user, icinga2_auth_pass, icinga2_insecure_tls)
30-
VALUES
31-
(1, 'icinga2', 'Local Icinga 2', 'https://localhost:5665', 'root', 'icinga', 'y');
32-
```
33-
34-
Then, you can launch the daemon with the following command.
35-
```go
36-
go run ./cmd/icinga-notifications --config config.yml
37-
```
20+
For more information about how to install or use Icinga Notifications,
21+
just follow the [documentation](https://icinga.com/docs/icinga-notifications/latest).
3822

3923
## License
4024

41-
Icinga Notifications is licensed under the terms of the [GNU General Public License Version 2](LICENSE).
25+
Icinga Notifications and the Icinga Notifications documentation are licensed under the terms of the
26+
[GNU General Public License Version 2](LICENSE).

‎config.example.yml

+3-3
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,9 @@ database:
1515
host: /run/postgresql
1616
#host: localhost
1717
#port: 5432
18-
user: icinga_notifications
19-
database: icinga_notifications
20-
#password: icinga_notifications
18+
user: notifications
19+
database: notifications
20+
#password: notifications
2121

2222
logging:
2323
# Default logging level. Can be set to 'fatal', 'error', 'warn', 'info' or 'debug'.

‎doc/01-About.md

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Icinga Notifications
2+
3+
!!! warning
4+
5+
This is an early preview version for you to try, but do not use this in production.
6+
There may still be severe bugs and incompatible changes may happen without any notice.
7+
At the moment, we don't yet provide any support for this.
8+
9+
Icinga Notifications is a set of components that processes received events from various sources, manages incidents and
10+
forwards notifications to predefined contacts, consisting of:
11+
12+
* The Icinga Notifications daemon, which receives events and sends notifications.
13+
* The [Icinga Notifications Web](https://icinga.com/docs/icinga-notifications-web/latest/doc/01-About/) module,
14+
which provides graphical configuration.
15+
* Icinga 2 and other sources that provide monitoring events that result in notifications.
16+
17+
## Big Picture
18+
19+
![Icinga Notifications Architecture](images/icinga-notifications-architecture.png)
20+
21+
Because Icinga Notifications consists of several components,
22+
this section tries to help understand how these components relate.
23+
24+
First, the Icinga Notifications configuration resides in a SQL database.
25+
It can be conveniently tweaked via Icinga Notifications Web directly from a web browser.
26+
The Icinga Notifications daemon uses this database to read the current configuration.
27+
28+
As in any Icinga setup, all host and service checks are defined in Icinga 2.
29+
By querying the Icinga 2 API, the Icinga Notifications daemon retrieves state changes, acknowledgements, and other events.
30+
These events are stored in the database and are available for further inspection in Icinga Notifications Web.
31+
Next to Icinga 2, other notification sources can be configured.
32+
33+
Depending on its configuration, the daemon will take action on these events.
34+
This optionally includes escalations that are sent through a channel plugin.
35+
Each such channel plugin implements a domain-specific transport, e.g., the `email` channel sends emails via SMTP.
36+
When configured, Icinga Notifications will use channel plugins to notify end users or talk to other APIs.
37+
38+
## Available Channels
39+
40+
Icinga Notifications comes with multiple channels out of the box:
41+
42+
* _email_: Email submission via SMTP
43+
* _rocketchat_: Rocket.Chat
44+
* _webhook_: Configurable HTTP/HTTPS queries for your backend
45+
46+
Additional custom channels can be developed independently of Icinga Notifications,
47+
following the [channel specification](10-Channels.md).
48+
49+
## Installation
50+
51+
To install Icinga Notifications see [Installation](02-Installation.md).
52+
53+
## License
54+
55+
Icinga Notifications and the Icinga Notifications documentation are licensed under the terms of the
56+
[GNU General Public License Version 2](../LICENSE).

‎doc/02-Installation.md

+109
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
<!-- {% if index %} -->
2+
# Installing Icinga Notifications
3+
4+
The recommended way to install Icinga Notifications is to use prebuilt packages
5+
for all supported platforms from our official release repository.
6+
Please follow the steps listed for your target operating system,
7+
which guide you through setting up the repository and installing Icinga Notifications.
8+
9+
To upgrade an existing Icinga Notifications installation to a newer version,
10+
see the [Upgrading](04-Upgrading.md) documentation for the necessary steps.
11+
12+
<!-- {% else %} -->
13+
<!-- {% if not icingaDocs %} -->
14+
## Installing the Package
15+
16+
The recommended way to install Icinga Notifications is to use prebuilt packages from our official release repository.
17+
If the [repository](https://packages.icinga.com) is not configured yet, please add it first.
18+
Then use your distribution's package manager to install the `icinga-notifications` package
19+
or install [from source](02-Installation.md.d/From-Source.md).
20+
<!-- {% endif %} --><!-- {# end if not icingaDocs #} -->
21+
22+
## Setting up the Database
23+
24+
A MySQL (≥5.5), MariaDB (≥10.1), or PostgreSQL (≥9.6) database is required to run Icinga Notifications.
25+
Please follow the steps listed for your target database,
26+
which guide you through setting up the database and user and importing the schema.
27+
28+
### Setting up a MySQL or MariaDB Database
29+
30+
If you use a version of MySQL < 5.7 or MariaDB < 10.2, the following server options must be set:
31+
32+
```
33+
innodb_file_format=barracuda
34+
innodb_file_per_table=1
35+
innodb_large_prefix=1
36+
```
37+
38+
Set up a MySQL database for Icinga Notifications:
39+
40+
```
41+
# mysql -u root -p
42+
43+
CREATE DATABASE notifications;
44+
CREATE USER 'notifications'@'localhost' IDENTIFIED BY 'CHANGEME';
45+
GRANT ALL ON notifications.* TO 'notifications'@'localhost';
46+
```
47+
48+
After creating the database, import the Icinga Notifications schema using the following command:
49+
50+
```
51+
mysql -u root -p notifications < /usr/share/icinga-notifications/schema/mysql/schema.sql
52+
```
53+
54+
### Setting up a PostgreSQL Database
55+
56+
Set up a PostgreSQL database for Icinga Notifications:
57+
58+
```
59+
# su -l postgres
60+
61+
createuser -P notifications
62+
createdb -E UTF8 --locale en_US.UTF-8 -T template0 -O notifications notifications
63+
echo 'CREATE EXTENSION IF NOT EXISTS citext;' | psql notifications
64+
```
65+
66+
The `CREATE EXTENSION` command requires the `postgresql-contrib` package.
67+
68+
Edit `pg_hba.conf`, insert the following before everything else:
69+
70+
```
71+
local all notifications md5
72+
host all notifications 0.0.0.0/0 md5
73+
host all notifications ::/0 md5
74+
```
75+
76+
To apply these changes, run `systemctl reload postgresql`.
77+
78+
After creating the database, import the Icinga Notifications schema using the following command:
79+
80+
```
81+
psql -U notifications notifications < /usr/share/icinga-notifications/schema/pgsql/schema.sql
82+
```
83+
84+
## Configuring Icinga Notifications
85+
86+
Icinga Notifications installs its configuration file to `/etc/icinga-notifications/config.yml`,
87+
pre-populating most of the settings for a local setup. Before running Icinga Notifications,
88+
adjust the database credentials and the Icinga Web 2 URL.
89+
The configuration file explains general settings.
90+
All available settings can be found under [Configuration](03-Configuration.md).
91+
92+
## Running Icinga Notifications
93+
94+
The `icinga-notifications` package automatically installs the necessary systemd unit files to run Icinga Notifications.
95+
Please run the following command to enable and start its service:
96+
97+
```
98+
systemctl enable --now icinga-notifications
99+
```
100+
101+
## Installing Icinga Notifications Web
102+
103+
With Icinga 2, Icinga Notifications and the database fully set up, it is now time to install Icinga Notifications Web,
104+
which connects to the database and allows configuring Icinga Notifications.
105+
106+
Please follow the
107+
[Icinga Notifications Web documentation](https://icinga.com/docs/icinga-notifications-web/latest/doc/02-Installation/).
108+
109+
<!-- {% endif %} --><!-- {# end else if index #} -->

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

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Installing Icinga Notifications from Source
2+
3+
Although the provided packages are highly recommended and are the only officially supported installation,
4+
it may be necessary to build the software manually, e.g., if there are no packages available for the target platform.
5+
6+
Please follow the build instructions in the [development section](30-Development.md)
7+
for more information about requirements and the `Makefile`-based build.
8+
9+
<!-- {% set from_source = True %} -->
10+
<!-- {% include "02-Installation.md" %} -->

0 commit comments

Comments
 (0)