README.md 3.48 KB
Newer Older
Navid Sassan's avatar
Navid Sassan committed
1
# Linuxfabrik Fork of the Icinga Director
Thomas Gelf's avatar
Thomas Gelf committed
2

Navid Sassan's avatar
Navid Sassan committed
3
## Motivation - Why we forked
Thomas Gelf's avatar
Thomas Gelf committed
4

Navid Sassan's avatar
Navid Sassan committed
5
We are managing the Icinga Director configuration of many Icinga2 Servers using the Icinga Director Basket Ex- and Import. Currently the basket matches objects using its _name_, which means that it is _impossible_ to rename existing objects. Instead, if renaming, a new object is created with the new name, requiring us to manually delete the object with the old name on every Icinga2 Server.
Thomas Gelf's avatar
Thomas Gelf committed
6

Navid Sassan's avatar
Navid Sassan committed
7
This is especially problematic with DataFields: If you change any attribute (for example the caption or just the description) the original Icinga Director Basket creates a _new_ DataField. Assuming one did not modify the field name, we now have two DataFields with the same field name. When deleting the first/old one, you will be prompted if the related vars should be wiped.
Thomas Gelf's avatar
Thomas Gelf committed
8

Navid Sassan's avatar
Navid Sassan committed
9
This behavior is ugly and misleading, and the problem simply exists because the Icinga Director is not relying on IDs in its database.
Thomas Gelf's avatar
Thomas Gelf committed
10

Navid Sassan's avatar
Navid Sassan committed
11
We changed that.
Thomas Gelf's avatar
Thomas Gelf committed
12

13

Navid Sassan's avatar
Navid Sassan committed
14
## Features
15

Navid Sassan's avatar
Navid Sassan committed
16
This fork of the Icinga Director implements [GUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier) for most of the database objects to make the handling of the director basket easier.
17

Navid Sassan's avatar
Navid Sassan committed
18
The following objects will be saved with a GUID in the database when they are created or imported from a basket:
19

Navid Sassan's avatar
Navid Sassan committed
20
21
22
23
24
25
26
27
28
* DataFields
* Commands
* Service Templates
* Service Sets
* Host Templates
* Notification Templates
* Timeperiods
* Dependencies
* DataLists
29

Navid Sassan's avatar
Navid Sassan committed
30
This allows the following tasks to be accomplished by importing a basket:
31

Navid Sassan's avatar
Navid Sassan committed
32
* Changing the name of objects listed above. Without GUIDs, this would always create a new object instead.
Navid Sassan's avatar
Navid Sassan committed
33
* DataFields: When renaming, applied custom variables (for example to a host) will be renamed as well. Sadly, this is only the case for Individual Service objects - when setting values as an override, they are stored as strings in the database and therefore not renamed.
Navid Sassan's avatar
Navid Sassan committed
34
35
* DataLists: Entries can be removed from the list. Note: This does not affect applied entries, as they are saved as strings in the database. See [Known Limitations](#known-limitations) below.
* Service Sets: Services can be removed from the set.
36
37


Navid Sassan's avatar
Navid Sassan committed
38
## Installation
39

Navid Sassan's avatar
Navid Sassan committed
40
41
42
43
44
45
The module needs modifications to the director MySQL/MariaDB database (provided in the `schema/guid.sql` file).
You can import the schema using the following command:
```bash
mysql -p -u root director < schema/guid.sql
```

Navid Sassan's avatar
Navid Sassan committed
46
Please follow the [original installation guide](https://git.linuxfabrik.ch/linuxfabrik/icingaweb2-module-director/-/blob/v1.7.2.2020111901/doc/02-Installation.md) but use our [latest release](https://git.linuxfabrik.ch/linuxfabrik/icingaweb2-module-director/-/releases) instead of the original director.
47

Navid Sassan's avatar
Navid Sassan committed
48
49
50

## Known limitations

Navid Sassan's avatar
Navid Sassan committed
51
* Currently the only supported database is MySQL/MariaDB.
Navid Sassan's avatar
Navid Sassan committed
52
53
* DataFields: Renaming a field only renames applied variables if they are set on an Individual Service objects - when setting values as an override, they are stored as strings in the database and therefore not renamed.
* DataLists: Renaming or removing an entry will only rename/remove the entry in the datalist, not the applied variables on other objects such as hosts or services.
Navid Sassan's avatar
Navid Sassan committed
54
55
56
57
58
59
60


## Future

* The GUIDs could be used to allow deletion of certain objects during the basket import, for example a deprecated service.
* The basket import could ignore the enabled/disabled state of objects, allowing us to customize the Icinga Director config on one system without it being overwritten by an import.
* We are in contact with the Icinga guys about this project.