From 978a1651bac3faf5e91ddba327bf39aeb6a4cb63 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 14 Apr 2024 15:28:59 +0200 Subject: Adding upstream version 0.10.0. Signed-off-by: Daniel Baumann --- doc/02-Installation.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/03-Configuration.md | 33 ++++++++++++++++++++ doc/80-Upgrading.md | 18 +++++++++++ 3 files changed, 134 insertions(+) create mode 100644 doc/02-Installation.md create mode 100644 doc/03-Configuration.md create mode 100644 doc/80-Upgrading.md (limited to 'doc') diff --git a/doc/02-Installation.md b/doc/02-Installation.md new file mode 100644 index 0000000..fe4b8e4 --- /dev/null +++ b/doc/02-Installation.md @@ -0,0 +1,83 @@ +# Installation + +## 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 + +## Database Setup + +### MySQL / MariaDB + +The module needs a MySQL/MariaDB database with the schema that's provided in the `etc/schema/mysql.sql` file. + +Example 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'; +``` + +After, you can import the schema using the following command: + +``` +mysql -p -u root reporting < schema/mysql.sql +``` + +## PostgreSQL + +The module needs a PostgreSQL database with the schema that's provided in the `etc/schema/postgresql.sql` file. + +Example command for creating the PostgreSQL database. Please change the password: + +```sql +CREATE USER reporting WITH PASSWORD 'secret'; +CREATE DATABASE reporting + WITH OWNER reporting + ENCODING 'UTF8' + LC_COLLATE = 'en_US.UTF-8' + LC_CTYPE = 'en_US.UTF-8'; +``` + +After, you can import the schema using the following command: + +``` +psql -U reporting reporting -a -f schema/postgresql.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 new file mode 100644 index 0000000..f06481c --- /dev/null +++ b/doc/03-Configuration.md @@ -0,0 +1,33 @@ +# Configuration + +1. [Backend](#backend) +2. [Mail](#mail) +3. [Permissions](#permissions) + +## Backend + +If not already done during the installation of Icinga Reporting, setup the 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. + +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. + +## Mail + +At `Configuration -> Modules -> reporting -> Mail` you can configure the address +that is used as the sender's address (From) in E-mails. + +## Permissions + +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) diff --git a/doc/80-Upgrading.md b/doc/80-Upgrading.md new file mode 100644 index 0000000..8252e6f --- /dev/null +++ b/doc/80-Upgrading.md @@ -0,0 +1,18 @@ +# Upgrading Icinga Reporting + +Upgrading Icinga Reporting is straightforward. +Usually the only manual steps involved are schema updates for the database. + +## 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 +if you're using a version of MySQL < 5.7 or MariaDB < 10.2. +Further, the start dates for the provided time frames **Last Year** and **Current Year** have been fixed. +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