diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/02-Installation.md | 69 | ||||
| -rw-r--r-- | doc/03-Configuration.md | 51 | ||||
| -rw-r--r-- | doc/80-Upgrading.md | 40 |
3 files changed, 94 insertions, 66 deletions
diff --git a/doc/02-Installation.md b/doc/02-Installation.md index fe4b8e4..8b04fff 100644 --- a/doc/02-Installation.md +++ b/doc/02-Installation.md @@ -1,40 +1,42 @@ -# Installation +# Installing Icinga Reporting + +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.0) -* Icinga Web 2 (>= 2.9) -* Icinga Web 2 libraries: - * [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (>= 0.8) - * [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 (≥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) -## Database Setup +## Setting up the Database -### MySQL / MariaDB +### Setting up a MySQL or MariaDB Database -The module needs a MySQL/MariaDB database with the schema that's provided in the `etc/schema/mysql.sql` file. +The module needs a MySQL/MariaDB database with the schema that's provided in the `schema/mysql.schema.sql` file. -Example command for creating the MySQL/MariaDB database. Please change the password: +You can use the following sample command for creating the MySQL/MariaDB database. Please change the password: ``` CREATE DATABASE reporting; -GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON reporting.* TO reporting@localhost IDENTIFIED BY 'secret'; +GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, CREATE VIEW, INDEX, EXECUTE ON reporting.* TO reporting@localhost IDENTIFIED BY 'secret'; ``` After, you can import the schema using the following command: ``` -mysql -p -u root reporting < schema/mysql.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 `etc/schema/postgresql.sql` file. +The module needs a PostgreSQL database with the schema that's provided in the `schema/pgsql.schema.sql` file. -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'; @@ -48,36 +50,7 @@ CREATE DATABASE reporting After, you can import the schema using the following command: ``` -psql -U reporting reporting -a -f schema/postgresql.sql +psql -U reporting reporting -a -f /usr/share/icingaweb2/modules/reporting/schema/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/03-Configuration.md b/doc/03-Configuration.md index f06481c..e789aef 100644 --- a/doc/03-Configuration.md +++ b/doc/03-Configuration.md @@ -1,20 +1,17 @@ # 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. +Icinga Reporting stores all its configuration in the database, therefore you need to create and configure a database +resource for it. -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 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 Icinga Reporting using the + `Configuration → Modules → reporting → Backend` menu. If you've used `reporting` + as name for the resource, this is optional. ## Mail @@ -25,9 +22,31 @@ 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 `systemd` service of this module uses this command as well. + +To configure this as a `systemd` service, copy the example service definition from +`/usr/share/icingaweb2/modules/reporting/config/systemd/icinga-reporting.service` +to `/etc/systemd/system/icinga-reporting.service`. + +You can run the following command to enable and start the daemon. + +``` +systemctl enable --now icinga-reporting.service +``` diff --git a/doc/80-Upgrading.md b/doc/80-Upgrading.md index 8252e6f..41b665c 100644 --- a/doc/80-Upgrading.md +++ b/doc/80-Upgrading.md @@ -3,7 +3,43 @@ Upgrading Icinga Reporting is straightforward. Usually the only manual steps involved are schema updates for the database. -## Upgrading to Version 0.9.1 <a id="upgrading-to-v0.9.1"></a> +## Upgrading to Version 1.0.0 + +Icinga Reporting version 1.0.0 requires a schema update for the database. +If you're already using Icinga Web version `>= 2.12`, then you don't need to perform any of these steps manually. +Icinga Web provides you the ability to perform such migrations in a simple way. You may be familiar with such an +automation if you're an Icinga Director user. For those who are not using the latest version of Icinga Web, please +follow the instructions below. + +> **Note** +> +> If you're not using Icinga Web migration automation, you may need to [populate](https://dev.mysql.com/doc/refman/8.0/en/time-zone-support.html#time-zone-installation) +> all the system named time zone information into your MSQL/MariaDB server. Otherwise, the migration may not succeed. + +You may use the following command to apply the database schema upgrade file: +<!-- {% if not icingaDocs %} --> + +**Note:** If you haven't installed this module from packages, then please adapt the schema path to the correct installation path. + +<!-- {% endif %} --> + +``` +# mysql -u root -p reporting /usr/share/icingaweb2/modules/reporting/schema/mysql-upgrades/1.0.0.sql +``` + +## Upgrading to Version 0.10.0 + +Icinga Reporting version 0.10.0 requires a schema update for the database. +A new table `template`, linked to table `report`, has been introduced. +Please find the upgrade script in **schema/mysql-upgrades**. + +You may use the following command to apply the database schema upgrade file: + +``` +# mysql -u root -p reporting <schema/mysql-upgrades/0.10.0.sql +``` + +## Upgrading to Version 0.9.1 Icinga Reporting version 0.9.1 requires a schema update for the database. The schema has been adjusted so that it is no longer necessary to adjust server settings @@ -14,5 +50,5 @@ Please find the upgrade script in **schema/mysql-migrations**. You may use the following command to apply the database schema upgrade file: ``` -# mysql -u root -p reporting <schema/mysql-migrations/v0.9.1.sql +# mysql -u root -p reporting <schema/mysql-upgrades/0.9.1.sql ``` |