Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: Initialize documentation #210

Merged
merged 1 commit into from
Jul 5, 2024
Merged

doc: Initialize documentation #210

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# These variables follow the naming convention from the GNU Make documentation
# but their defaults correspond to the rest of the code (note that changing
# libexecdir here wouldn't affect the default path for the channel plugin
# directory used by the dameon for example).
# directory used by the daemon for example).
#
# https://www.gnu.org/software/make/manual/html_node/Directory-Variables.html
prefix ?= /usr
Expand Down
43 changes: 14 additions & 29 deletions README.md
View file
Open in desktop
oxzi marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
@@ -1,41 +1,26 @@
# Icinga Notifications

> **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 yet provide any support for this.
> [!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 yet provide any support for this.

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
* The Icinga Notifications daemon (this repository), which receives events and sends notifications.
* The [Icinga Notifications Web](https://github.com/Icinga/icinga-notifications-web) module,
which provides graphical configuration.
* Icinga 2 and other sources that provide monitoring events that result in notifications.

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

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

Next, you need to provide a `config.yml` file, similar to the [example config](config.example.yml), for the daemon.
It is required that you have created a new database and imported the [schema](schema/pgsql/schema.sql) file beforehand.
> **Note**
> At the moment **PostgreSQL** is the only database backend we support.

Additionally, it also requires you to manually insert items into the **source** table before starting the daemon.
```sql
INSERT INTO source
(id, type, name, icinga2_base_url, icinga2_auth_user, icinga2_auth_pass, icinga2_insecure_tls)
VALUES
(1, 'icinga2', 'Local Icinga 2', 'https://localhost:5665', 'root', 'icinga', 'y');
```

Then, you can launch the daemon with the following command.
```go
go run ./cmd/icinga-notifications --config config.yml
```
For more information about how to install or use Icinga Notifications,
just follow the [documentation](https://icinga.com/docs/icinga-notifications/latest).

## License

Icinga Notifications is licensed under the terms of the [GNU General Public License Version 2](LICENSE).
Icinga Notifications and the Icinga Notifications documentation are licensed under the terms of the
[GNU General Public License Version 2](LICENSE).
6 changes: 3 additions & 3 deletions config.example.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@ database:
host: /run/postgresql
#host: localhost
#port: 5432
user: icinga_notifications
database: icinga_notifications
#password: icinga_notifications
user: notifications
database: notifications
#password: notifications

logging:
# Default logging level. Can be set to 'fatal', 'error', 'warn', 'info' or 'debug'.
Expand Down
56 changes: 56 additions & 0 deletions doc/01-About.md
View file
Open in desktop
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(This note is not related to this file in particular, I just wanted to create a thread and don't know another way to do this here.)

I am a bit unhappy with the numbering of the markdown files by their filename. This layout was copied from the other Icinga documentations and I would expect a certain degree of similarity between the projects.

However, this layout enforces a ordering by the names from the beginning, which is hard to change later, as it will break links, resulting in dead URLs. For example, in Icinga DB I once wanted to add a new section between two already existing ones, but there is no real possibility to add something in between1.

It would be possible to leave greater gaps, but this would also look weird. I would like to hear your comment on this, @julianbrost. Thanks :)

Footnotes

  1. Except of hacks like naming something 03-01-Foo.md if it should go between 03-Configuration.md and 04-Upgrading.md. ↩

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This layout was copied from the other Icinga documentations and I would expect a certain degree of similarity between the projects.

If we would consider breaking our own conventions, we could manually populate MKDocs' nav and don't prefix files with numbers. This, however, would also require patching the build-docs.rb script.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be honest, I never thought about this. But indeed, it doesn't really make sense to me that the URL for example is https://icinga.com/docs/icinga-2/latest/doc/14-features/ instead of just https://icinga.com/docs/icinga-2/latest/doc/features/.

we could manually populate MKDocs' nav and don't prefix files with numbers. This, however, would also require patching the build-docs.rb script.

I'm not familiar with MKDocs either, so I don't know what its nav is, but it doesn't sound wrong to me.

By the way, leaving gaps wouldn't be unheard of, see https://github.com/Icinga/icingaweb2-module-director/tree/master/doc and https://github.com/Icinga/icinga-powershell-framework/tree/master/doc for example.

Copy link
Member

@ncosta-ic ncosta-ic Jun 26, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed, proper permalinks regardless of the given file name, would be really handy. There's a whole discussion about it over at squidfunk/mkdocs-material#3758

The whole build-docs.rb wrapper is pretty hacky alltogether and even destroyed my local git repository because of the wonderful rm -rf instruction contained in it...
A better solution would be to rewrite our existing build-docs.rb functionality into a Python hook1.
We could also include our own solution to the url problem by doing so.
I would be up for that task as I have a lot of experience with Python - if we were to decide to go for such a change.

Footnotes

  1. https://www.mkdocs.org/user-guide/configuration/#hooks ↩

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm all for improving things there if you've looked into it already and have ideas how to do it better. But sounds something to better track in central place rather than here. If we change something, that would affect most projects anyways. Also, this shouldn't block anything here, the only question is whether you want to add gaps in the numbers for the moment.

By the way, keeping URLs working with a change in that direction should be simple by redirecting NNN-foobar to foobar.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the moment, I added some gaps between the numbering of the later sections as one might expect something to pop up there.

After some potential future change, a simple RewriteRule ^/doc/([a-z0-9-]+)/[0-9]+-(.*) /doc/$1/$2 [R]1 should do, as @julianbrost also suggested.

Footnotes

  1. Untested, of course 🙃 ↩

Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Icinga Notifications

!!! 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 yet provide any support for this.

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, which receives events and sends notifications.
* The [Icinga Notifications Web](https://icinga.com/docs/icinga-notifications-web/latest/doc/01-About/) module,
which provides graphical configuration.
* Icinga 2 and other sources that provide monitoring events that result in notifications.

## Big Picture

![Icinga Notifications Architecture](images/icinga-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 such channel plugin 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 your backend

Additional custom channels can be developed independently of Icinga Notifications,
following the [channel specification](10-Channels.md).

## 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](../LICENSE).
109 changes: 109 additions & 0 deletions doc/02-Installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
<!-- {% 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.

<!-- {% else %} -->
<!-- {% if not icingaDocs %} -->
## Installing the Package

The recommended way to install Icinga Notifications is to use prebuilt packages from our official release repository.
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` package
or install [from source](02-Installation.md.d/From-Source.md).
<!-- {% endif %} --><!-- {# end if not icingaDocs #} -->

## 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 notifications;
CREATE USER 'notifications'@'localhost' IDENTIFIED BY 'CHANGEME';
GRANT ALL ON notifications.* TO 'notifications'@'localhost';
```

After creating the database, import the Icinga Notifications schema using the following command:

```
mysql -u root -p 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 notifications
createdb -E UTF8 --locale en_US.UTF-8 -T template0 -O notifications notifications
echo 'CREATE EXTENSION IF NOT EXISTS citext;' | psql notifications
```

The `CREATE EXTENSION` command requires the `postgresql-contrib` package.

Edit `pg_hba.conf`, insert the following before everything else:

```
local all notifications md5
host all notifications 0.0.0.0/0 md5
host all 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 notifications 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 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:

```
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.

Please follow the
[Icinga Notifications Web documentation](https://icinga.com/docs/icinga-notifications-web/latest/doc/02-Installation/).

<!-- {% endif %} --><!-- {# end else if index #} -->
10 changes: 10 additions & 0 deletions doc/02-Installation.md.d/From-Source.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Installing Icinga Notifications from Source

Although the provided packages are highly recommended and are the only officially supported installation,
it may be necessary to build the software manually, e.g., if there are no packages available for the target platform.

Please follow the build instructions in the [development section](30-Development.md)
for more information about requirements and the `Makefile`-based build.

<!-- {% set from_source = True %} -->
<!-- {% include "02-Installation.md" %} -->
Loading
Loading