From 12df24651165bc3dfb1626567b493846195f6ed6 Mon Sep 17 00:00:00 2001 From: Yonas Habteab Date: Tue, 12 Sep 2023 14:41:36 +0200 Subject: [PATCH] Recommend package installs & enhance installation & configuration docs --- doc/01-About.md | 18 ++++++ doc/02-Installation.md | 85 +++++++++++-------------- doc/02-Installation.md.d/From-Source.md | 16 +++++ doc/03-Configuration.md | 56 +++++++++++----- 4 files changed, 110 insertions(+), 65 deletions(-) create mode 100644 doc/01-About.md create mode 100644 doc/02-Installation.md.d/From-Source.md diff --git a/doc/01-About.md b/doc/01-About.md new file mode 100644 index 00000000..aa517437 --- /dev/null +++ b/doc/01-About.md @@ -0,0 +1,18 @@ +# Icinga Reporting + +Icinga Reporting is the central component for reporting related functionality in the monitoring web frontend and +framework Icinga Web. The engine allows you to create reports over a specified time period for ad-hoc and scheduled +generation of reports. Other modules use the provided functionality in order to provide concrete reports. + +## Host/Service SLA Reports + +With Icinga DB Web there is no additional module required. + +If you are still using the monitoring module, please also install the +[idoreports](https://github.com/Icinga/icingaweb2-module-idoreports) module. + +## Documentation + +* [Installation](02-Installation.md) +* [Configuration](03-Configuration.md) +* [Upgrading](80-Upgrading.md) diff --git a/doc/02-Installation.md b/doc/02-Installation.md index cc39b1f7..53068dd9 100644 --- a/doc/02-Installation.md +++ b/doc/02-Installation.md @@ -1,24 +1,34 @@ -# Installation + +# Installing Icinga Reporting -## Requirements +The recommended way to install Icinga Reporting and its dependencies is to use prebuilt packages for all supported +platforms from our official release repository. Please note that [Icinga Web](https://icinga.com/docs/icinga-web) is +required and if it is not already set up, it is best to do this first. -* PHP (>= 7.0) -* Icinga Web 2 (>= 2.9) -* Icinga Web 2 libraries: - * [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (>= 0.12) - * [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (>= 0.10) -* Icinga Web 2 modules: - * [Icinga PDF Export](https://github.com/Icinga/icingaweb2-module-pdfexport) (>= 0.10) -* MySQL / MariaDB or PostgreSQL -* php-mbstring +To upgrade an existing Icinga Reporting installation to a newer version, see the [Upgrading](80-Upgrading.md) documentation +for the necessary steps. + + -## Database Setup +## Installing the Package -### MySQL / MariaDB +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-reporting` package +or install [from source](02-Installation.md.d/From-Source.md). + -The module needs a MySQL/MariaDB database with the schema that's provided in the `etc/schema/mysql.schema.sql` file. +## Setting up the Database -Example command for creating the MySQL/MariaDB database. Please change the password: +### Setting up a MySQL or MariaDB Database + +The module needs a MySQL/MariaDB database with the schema that's provided in the `/usr/share/icingaweb2/modules/reporting/schema/mysql.schema.sql` file. + + +**Note:** If you haven't installed this module from packages, then please adapt the schema path to the correct installation path. + + + +You can use the following sample command for creating the MySQL/MariaDB database. Please change the password: ``` CREATE DATABASE reporting; @@ -28,14 +38,19 @@ GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE, CREATE VIEW, INDEX, EXECUTE After, you can import the schema using the following command: ``` -mysql -p -u root reporting < schema/mysql.schema.sql +mysql -p -u root reporting < /usr/share/icingaweb2/modules/reporting/schema/mysql.schema.sql ``` -## PostgreSQL +## Setting up a PostgreSQL Database + +The module needs a PostgreSQL database with the schema that's provided in the `/usr/share/icingaweb2/modules/reporting/schema/pgsql.schema.sql` file. + -The module needs a PostgreSQL database with the schema that's provided in the `etc/schema/pgsql.schema.sql` file. +**Note:** If you haven't installed this module from packages, then please adapt the schema path to the correct installation path. -Example command for creating the PostgreSQL database. Please change the password: + + +You can use the following sample command for creating the PostgreSQL database. Please change the password: ```sql CREATE USER reporting WITH PASSWORD 'secret'; @@ -49,36 +64,8 @@ CREATE DATABASE reporting After, you can import the schema using the following command: ``` -psql -U reporting reporting -a -f schema/pgsql.schema.sql +psql -U reporting reporting -a -f /usr/share/icingaweb2/modules/reporting/pgsql.schema.sql ``` -## Module Installation - -1. Install it [like any other module](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation). -Use `reporting` as name. - -2. Once you've set up the database, create a new Icinga Web 2 resource for it using the -`Configuration -> Application -> Resources` menu. Make sure that you set the character set to `utf8mb4`. - -3. The next step involves telling the Reporting module which database resource to use. This can be done in -`Configuration -> Modules -> reporting -> Backend`. If you've used `reporting` as name for the resource, -you can skip this step. - This concludes the installation. Now continue with the [configuration](03-Configuration.md). - -## Scheduler Daemon - -There is a daemon for generating and distributing reports on a schedule if configured: - -``` -icingacli reporting schedule run -``` - -This command schedules the execution of all applicable reports. - -You may configure this command as `systemd` service. Just copy the example service definition from -`config/systemd/icinga-reporting.service` to `/etc/systemd/system/icinga-reporting.service` and enable it afterwards: - -``` -systemctl enable icinga-reporting.service -``` + 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..6ab03bad --- /dev/null +++ b/doc/02-Installation.md.d/From-Source.md @@ -0,0 +1,16 @@ +# Installing Icinga Reporting 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 `reporting` as the module name. The following requirements must also be met. + +## Requirements + +* PHP (≥7.2) +* MySQL or PostgreSQL PDO PHP libraries +* The following PHP modules must be installed: `mbstring` +* [Icinga Web](https://github.com/Icinga/icingaweb2) (≥2.9) +* [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (≥0.13.0) +* [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (≥0.12.0) + + diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md index f06481ce..ea8fe55d 100644 --- a/doc/03-Configuration.md +++ b/doc/03-Configuration.md @@ -1,20 +1,16 @@ # Configuration -1. [Backend](#backend) -2. [Mail](#mail) -3. [Permissions](#permissions) +Icinga Reporting is configured via the web interface. Below you will find an overview of the necessary settings. ## Backend -If not already done during the installation of Icinga Reporting, setup the reporting database backend now. +Configuring the Icinga Reporting database backend now. -Create a new [Icinga Web 2 resource](https://icinga.com/docs/icingaweb2/latest/doc/04-Resources/#database) -for [Icinga Reporting's database](https://icinga.com/docs/icinga-reporting/latest/doc/02-Installation/#database-setup) -using the `Configuration -> Application -> Resources` menu. +1. Create a new resource for the Icinga Reporting via the `Configuration -> Application -> Resources` menu. -Then tell Icinga Reporting which database resource to use. This can be done in -`Configuration -> Modules -> reporting -> Backend`. If you've used `reporting` -as name for the resource, this is optional. +2. Configure the resource you just created as the database connection for the Icinga Reporting module using the + `Configuration → Modules → reporting → Backend` menu. If you've used `reporting` + as name for the resource, this is optional. ## Mail @@ -25,9 +21,37 @@ that is used as the sender's address (From) in E-mails. There are four permissions that can be used to control what can be managed by whom. -Permission | Applies to ----------------------|---------------- -reporting/reports | Reports (create, edit, delete) -reporting/schedules | Schedules (create, edit, delete) -reporting/templates | Templates (create, edit, delete) -reporting/timeframes | Timeframes (create, edit, delete) +| Permission | Applies to | +|----------------------|-----------------------------------| +| reporting/reports | Reports (create, edit, delete) | +| reporting/schedules | Schedules (create, edit, delete) | +| reporting/templates | Templates (create, edit, delete) | +| reporting/timeframes | Timeframes (create, edit, delete) | + +## Icinga Reporting Daemon + +There is a daemon for generating and distributing reports on a schedule if configured: + +``` +icingacli reporting schedule run +``` + +This command schedules the execution of all applicable reports. + +The default `systemd` service of this module, shipped with package installations, uses this command as well. + + + +> **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/reporting/config/systemd/icinga-reporting.service` +> to `/etc/systemd/system/icinga-reporting.service`. + + + +Afterwards, you can run the following command to enable and start the daemon. + +``` +systemctl enable --now icinga-reporting.service +```