summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-14 13:29:17 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-14 13:29:17 +0000
commitc22a2c3ebc334fd7a891370e43a841d914893d47 (patch)
tree8a2c06166a1025a97cad914e1ce9da2bc78d646c /doc
parentReleasing progress-linux version 0.10.0-2~progress7.99u1. (diff)
downloadicingaweb2-module-reporting-c22a2c3ebc334fd7a891370e43a841d914893d47.tar.xz
icingaweb2-module-reporting-c22a2c3ebc334fd7a891370e43a841d914893d47.zip
Merging upstream version 1.0.1.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc')
-rw-r--r--doc/02-Installation.md69
-rw-r--r--doc/03-Configuration.md51
-rw-r--r--doc/80-Upgrading.md40
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
```