summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-28 12:42:52 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-28 12:42:52 +0000
commitda0f8427204ad57aad08059906df0ea10a7ccf31 (patch)
treeccda92692e296a50dac104945f62b4402d5e4447 /doc
parentInitial commit. (diff)
downloadicingaweb2-module-cube-da0f8427204ad57aad08059906df0ea10a7ccf31.tar.xz
icingaweb2-module-cube-da0f8427204ad57aad08059906df0ea10a7ccf31.zip
Adding upstream version 1.2.2.upstream/1.2.2upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc')
-rw-r--r--doc/01-About.md58
-rw-r--r--doc/02-Installation.md235
-rw-r--r--doc/02-Installation.md.d/01-Amazon-Linux.md3
-rw-r--r--doc/02-Installation.md.d/02-CentOS.md3
-rw-r--r--doc/02-Installation.md.d/03-Debian.md3
-rw-r--r--doc/02-Installation.md.d/04-RHEL.md3
-rw-r--r--doc/02-Installation.md.d/05-SLES.md3
-rw-r--r--doc/02-Installation.md.d/06-Ubuntu.md3
-rw-r--r--doc/02-Installation.md.d/07-From-Source.md3
-rw-r--r--doc/img/cube_action-links.pngbin0 -> 33474 bytes
-rw-r--r--doc/img/cube_director.pngbin0 -> 45415 bytes
-rw-r--r--doc/img/cube_move-up.pngbin0 -> 49941 bytes
-rw-r--r--doc/img/cube_simple.pngbin0 -> 44872 bytes
-rw-r--r--doc/img/cube_slice.pngbin0 -> 24887 bytes
14 files changed, 314 insertions, 0 deletions
diff --git a/doc/01-About.md b/doc/01-About.md
new file mode 100644
index 0000000..c07095a
--- /dev/null
+++ b/doc/01-About.md
@@ -0,0 +1,58 @@
+# Icinga Cube
+
+The Icinga Cube is a tiny but useful [Icinga Web](https://github.com/Icinga/icingaweb2)
+module. It currently shows host and service statistics (total count, health) grouped by
+various custom variables in multiple dimensions.
+
+![Cube - Overview](img/cube_simple.png)
+
+It will be your new best friend in case you are running a large environment and
+want to get a quick answers to questions like:
+
+* Which project uses how many servers per environment at which location/site?
+ * Who occupies most servers?
+ * How many of those are used in production?
+ * Which project has only development and test boxes?
+* Which operating system is used for which project and in which environment?
+ * Do we still have Debian Lenny?
+ * Which projects are to blame for this?
+ * Do we have applications where the operating systems used differ in staging
+ and production?
+* Which project uses which operating system version for which application?
+ * Which projects have homogeneous environments?
+ * Which projects are at a consistent patch level?
+ * How many RHEL 6 variants (6.1, 6.2, 6.3...) do we use?
+ * Who is running the oldest ones? In production?
+* Which projects are still using physical servers in which environment?
+
+For Businessmen - Drill and Slice
+---------------------------------
+
+Get answers to your questions. Quick and fully autonomous, using the cube
+requires no technical skills. Choose amongst all available dimensions and rotate
+the Cube to fit your needs.
+
+![Cube - Configure Dimensions](img/cube_move-up.png)
+
+Want to drill down? Choose a slice and get your answers:
+
+![Cube - Configure Dimensions](img/cube_slice.png)
+
+All facts configured for systems monitored by [Icinga](https://www.icinga.com/)
+can be used for your research.
+
+For Icinga Director users
+-------------------------
+
+![Cube - Action Links](img/cube_action-links.png)
+
+In case you are using the [Icinga Director](https://github.com/Icinga/icingaweb2-module-director),
+in addition to the multi-selection/edit feature the cube provides a nice way to
+modify multiple hosts at once.
+
+![Cube - Director multi-edit](img/cube_director.png)
+
+Installation
+------------
+
+To install Icinga Cube see [Installation](02-Installation.md).
diff --git a/doc/02-Installation.md b/doc/02-Installation.md
new file mode 100644
index 0000000..ef094bd
--- /dev/null
+++ b/doc/02-Installation.md
@@ -0,0 +1,235 @@
+<!-- {% if index %} -->
+# Installing Icinga Cube
+
+The recommended way to install Icinga Cube 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 Cube.
+
+<!-- {% else %} -->
+<!-- {% if not from_source %} -->
+## Adding Icinga Package Repository
+
+The recommended way to install Icinga Cube is to use prebuilt packages from our official release repository.
+
+!!! tip
+
+ If you install Icinga Cube on a node that has Icinga 2, Icinga DB or Icinga Web installed via packages,
+ proceed to [installing the Icinga Cube package](#installing-icinga-cube-package) as
+ the repository is already configured.
+
+Here's how to add the official release repository:
+
+<!-- {% if amazon_linux %} -->
+<!-- {% if not icingaDocs %} -->
+### Amazon Linux 2 Repository
+<!-- {% endif %} -->
+!!! info
+
+ A paid repository subscription is required for Amazon Linux 2 repositories. Get more information on
+ [icinga.com/subscription](https://icinga.com/subscription).
+
+ Don't forget to fill in the username and password section with appropriate credentials in the local .repo file.
+
+```bash
+rpm --import https://packages.icinga.com/icinga.key
+wget https://packages.icinga.com/subscription/amazon/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
+```
+<!-- {% endif %} -->
+
+<!-- {% if centos %} -->
+<!-- {% if not icingaDocs %} -->
+### CentOS Repository
+<!-- {% endif %} -->
+```bash
+rpm --import https://packages.icinga.com/icinga.key
+wget https://packages.icinga.com/centos/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
+```
+<!-- {% endif %} -->
+
+<!-- {% if debian %} -->
+<!-- {% if not icingaDocs %} -->
+### Debian Repository
+<!-- {% endif %} -->
+
+```bash
+apt-get update
+apt-get -y install apt-transport-https wget gnupg
+
+wget -O - https://packages.icinga.com/icinga.key | apt-key add -
+
+DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
+ echo "deb https://packages.icinga.com/debian icinga-${DIST} main" > \
+ /etc/apt/sources.list.d/${DIST}-icinga.list
+ echo "deb-src https://packages.icinga.com/debian icinga-${DIST} main" >> \
+ /etc/apt/sources.list.d/${DIST}-icinga.list
+
+apt-get update
+```
+<!-- {% endif %} -->
+
+<!-- {% if rhel %} -->
+<!-- {% if not icingaDocs %} -->
+### RHEL Repository
+<!-- {% endif %} -->
+!!! info
+
+ A paid repository subscription is required for RHEL repositories. Get more information on
+ [icinga.com/subscription](https://icinga.com/subscription).
+
+ Don't forget to fill in the username and password section with appropriate credentials in the local .repo file.
+
+```bash
+rpm --import https://packages.icinga.com/icinga.key
+wget https://packages.icinga.com/subscription/rhel/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
+```
+<!-- {% endif %} -->
+
+<!-- {% if sles %} -->
+<!-- {% if not icingaDocs %} -->
+### SLES Repository
+<!-- {% endif %} -->
+!!! info
+
+ A paid repository subscription is required for SLES repositories. Get more information on
+ [icinga.com/subscription](https://icinga.com/subscription).
+
+ Don't forget to fill in the username and password section with appropriate credentials in the local .repo file.
+
+```bash
+rpm --import https://packages.icinga.com/icinga.key
+
+zypper ar https://packages.icinga.com/subscription/sles/ICINGA-release.repo
+zypper ref
+```
+<!-- {% endif %} -->
+
+<!-- {% if ubuntu %} -->
+<!-- {% if not icingaDocs %} -->
+### Ubuntu Repository
+<!-- {% endif %} -->
+
+```bash
+apt-get update
+apt-get -y install apt-transport-https wget gnupg
+
+wget -O - https://packages.icinga.com/icinga.key | apt-key add -
+
+. /etc/os-release; if [ ! -z ${UBUNTU_CODENAME+x} ]; then DIST="${UBUNTU_CODENAME}"; else DIST="$(lsb_release -c| awk '{print $2}')"; fi; \
+ echo "deb https://packages.icinga.com/ubuntu icinga-${DIST} main" > \
+ /etc/apt/sources.list.d/${DIST}-icinga.list
+ echo "deb-src https://packages.icinga.com/ubuntu icinga-${DIST} main" >> \
+ /etc/apt/sources.list.d/${DIST}-icinga.list
+
+apt-get update
+```
+<!-- {% endif %} -->
+
+## Installing Icinga Cube Package
+
+Use your distribution's package manager to install the `icinga-cube` package as follows:
+
+<!-- {% if amazon_linux %} -->
+<!-- {% if not icingaDocs %} -->
+#### Amazon Linux 2
+<!-- {% endif %} -->
+```bash
+yum install icinga-cube
+```
+<!-- {% endif %} -->
+
+<!-- {% if centos %} -->
+<!-- {% if not icingaDocs %} -->
+#### CentOS
+<!-- {% endif %} -->
+!!! info
+
+ Note that installing Icinga Cube is only supported on CentOS 7 as CentOS 8 is EOL.
+
+```bash
+yum install icinga-cube
+```
+<!-- {% endif %} -->
+
+<!-- {% if debian or ubuntu %} -->
+<!-- {% if not icingaDocs %} -->
+#### Debian / Ubuntu
+<!-- {% endif %} -->
+```bash
+apt-get install icinga-cube
+```
+<!-- {% endif %} -->
+
+<!-- {% if rhel %} -->
+#### RHEL 8 or Later
+
+```bash
+dnf install icinga-cube
+```
+
+#### RHEL 7
+
+```bash
+yum install icinga-cube
+```
+<!-- {% endif %} -->
+
+<!-- {% if sles %} -->
+<!-- {% if not icingaDocs %} -->
+#### SLES
+<!-- {% endif %} -->
+```bash
+zypper install icinga-cube
+```
+<!-- {% endif %} -->
+
+<!-- {% else %} --><!-- {# end if not from_source #} -->
+<!-- {% if not icingaDocs %} -->
+## Installing Icinga Cube from Source
+<!-- {% endif %} -->
+
+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 `cube` as the module name. The following requirements must also be met.
+
+### Requirements
+
+* PHP (≥7.2)
+* [Icinga Web](https://github.com/Icinga/icingaweb2) (≥2.9)
+* [Icinga DB Web](https://github.com/Icinga/icingadb-web) (≥1.0)
+* [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (≥0.9)
+
+If you are using PostgreSQL, you need at least 9.5 which provides the `ROLLUP` feature.
+<!-- {% endif %} --><!-- {# end else if not from_source #} -->
+
+## Configuring Icinga Cube
+
+<!-- {% if not from_source %} -->
+The Icinga Web PHP framework is required to configure and run the Icinga Cube.
+Package installations of `icinga-cube` already set up the necessary dependencies.
+
+If Icinga Web has not been installed or set up before,
+you have completed the instructions here and can proceed to
+<!-- {% if amazon_linux %} -->
+[install the web server on Amazon Linux](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/06-Amazon-Linux/#install-the-web-server),
+<!-- {% endif %} -->
+<!-- {% if centos %} -->
+[install the web server on CentOS](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/03-CentOS/#install-the-web-server),
+<!-- {% endif %} -->
+<!-- {% if debian %} -->
+[install the web server on Debian](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/01-Debian/#install-the-web-server),
+<!-- {% endif %} -->
+<!-- {% if rhel %} -->
+[install the web server on RHEL](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/04-RHEL/#install-the-web-server),
+<!-- {% endif %} -->
+<!-- {% if sles %} -->
+[install the web server on SLES](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/05-SLES/#install-the-web-server),
+<!-- {% endif %} -->
+<!-- {% if ubuntu %} -->
+[install the web server on Ubuntu](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/02-Ubuntu/#install-the-web-server),
+<!-- {% endif %} -->
+which will then take you to the web-based setup wizard, which also allows you to enable the Icinga Cube.
+<!-- {% endif %} --><!-- {# end if not from_source #} -->
+
+For Icinga Web setups already running, log in to Icinga Web with a privileged user and enable the Icinga Cube.
+<!-- {% endif %} --><!-- {# end else if index #} -->
diff --git a/doc/02-Installation.md.d/01-Amazon-Linux.md b/doc/02-Installation.md.d/01-Amazon-Linux.md
new file mode 100644
index 0000000..30340b1
--- /dev/null
+++ b/doc/02-Installation.md.d/01-Amazon-Linux.md
@@ -0,0 +1,3 @@
+# Installing Icinga Cube on Amazon Linux
+<!-- {% set amazon_linux = True %} -->
+<!-- {% include "02-Installation.md" %} -->
diff --git a/doc/02-Installation.md.d/02-CentOS.md b/doc/02-Installation.md.d/02-CentOS.md
new file mode 100644
index 0000000..aaaaf1e
--- /dev/null
+++ b/doc/02-Installation.md.d/02-CentOS.md
@@ -0,0 +1,3 @@
+# Installing Icinga Cube on CentOS
+<!-- {% set centos = True %} -->
+<!-- {% include "02-Installation.md" %} -->
diff --git a/doc/02-Installation.md.d/03-Debian.md b/doc/02-Installation.md.d/03-Debian.md
new file mode 100644
index 0000000..22c9603
--- /dev/null
+++ b/doc/02-Installation.md.d/03-Debian.md
@@ -0,0 +1,3 @@
+# Installing Icinga Cube on Debian
+<!-- {% set debian = True %} -->
+<!-- {% include "02-Installation.md" %} -->
diff --git a/doc/02-Installation.md.d/04-RHEL.md b/doc/02-Installation.md.d/04-RHEL.md
new file mode 100644
index 0000000..fb6f738
--- /dev/null
+++ b/doc/02-Installation.md.d/04-RHEL.md
@@ -0,0 +1,3 @@
+# Installing Icinga Cube on RHEL
+<!-- {% set rhel = True %} -->
+<!-- {% include "02-Installation.md" %} -->
diff --git a/doc/02-Installation.md.d/05-SLES.md b/doc/02-Installation.md.d/05-SLES.md
new file mode 100644
index 0000000..eb7bba7
--- /dev/null
+++ b/doc/02-Installation.md.d/05-SLES.md
@@ -0,0 +1,3 @@
+# Installing Icinga Cube on SLES
+<!-- {% set sles = True %} -->
+<!-- {% include "02-Installation.md" %} -->
diff --git a/doc/02-Installation.md.d/06-Ubuntu.md b/doc/02-Installation.md.d/06-Ubuntu.md
new file mode 100644
index 0000000..0a4cbf2
--- /dev/null
+++ b/doc/02-Installation.md.d/06-Ubuntu.md
@@ -0,0 +1,3 @@
+# Installing Icinga Cube on Ubuntu
+<!-- {% set ubuntu = True %} -->
+<!-- {% include "02-Installation.md" %} -->
diff --git a/doc/02-Installation.md.d/07-From-Source.md b/doc/02-Installation.md.d/07-From-Source.md
new file mode 100644
index 0000000..a5cb8d1
--- /dev/null
+++ b/doc/02-Installation.md.d/07-From-Source.md
@@ -0,0 +1,3 @@
+# Installing Icinga Cube from Source
+<!-- {% set from_source = True %} -->
+<!-- {% include "02-Installation.md" %} -->
diff --git a/doc/img/cube_action-links.png b/doc/img/cube_action-links.png
new file mode 100644
index 0000000..79542e9
--- /dev/null
+++ b/doc/img/cube_action-links.png
Binary files differ
diff --git a/doc/img/cube_director.png b/doc/img/cube_director.png
new file mode 100644
index 0000000..3fc3730
--- /dev/null
+++ b/doc/img/cube_director.png
Binary files differ
diff --git a/doc/img/cube_move-up.png b/doc/img/cube_move-up.png
new file mode 100644
index 0000000..980a503
--- /dev/null
+++ b/doc/img/cube_move-up.png
Binary files differ
diff --git a/doc/img/cube_simple.png b/doc/img/cube_simple.png
new file mode 100644
index 0000000..0690d59
--- /dev/null
+++ b/doc/img/cube_simple.png
Binary files differ
diff --git a/doc/img/cube_slice.png b/doc/img/cube_slice.png
new file mode 100644
index 0000000..3aff4db
--- /dev/null
+++ b/doc/img/cube_slice.png
Binary files differ