First time installing module (director) to IcingaWeb2

I have been using Icinga for a number of years now and I have a large investment in many conf files in my conf.d directory so have been reluctant to migrate to director. And BTW, I think the concept of apply blocks with assign where/ignore where attributes is brilliant and powerful.

Now I am setting up a centos 8 stream on my kvm lab box to see how Director works. Also, obviously trying out Centos 8 Stream. My experience is not good. So in the hope of not offending and hoping to advance the software, here is some feedback for your consideration.

I installed icinga2, latest, very easily and manually, step by step, by the book. I installed icingaweb2 with the same official documentation but got very confused in the setup wizard and had to go back to the beginning a few times to try and understand what should be plain vanilla entries. I found a few sites of page-by-page images by users but nothing in the official documentation. I recommend for Icingaweb2, to make it more obvious and tie the steps I performed in the Icinga2 installation with those of the wizard. Perhaps a little more explanation on the idea of icinga database vs icingaweb2 database, or the name of the Monitoring IDO Resource. I don’t recall defining icinga_ido. I went step by step and only changed the password values, and I made all the passwords the same so I would not have to guess later on which was which.

But finally I scraped together bits of what I need and I finally get icingaweb2 running.

Next to install the module, Director.

OK I found the modules section of Icingaweb2 site, but I did not see Director as an option. I thought I would simply check a box to turn on director, or to at least install it. That’s what I expected, perhaps wrongly, but there was some disappointment.

I went to the docs pages for Director and read the brief promotional material in the Introduction page. There is no way that reading this page is enough to prepare me for “getting started”. It was not really informative about what Director does and mainly describes why it’s so great. On to the Installation page. The first thing I see is a list of 19 bullet points for prerequisites. Wow. I do these kinds of projects at home in the evenings so maybe tomorrow. Ah, I pushed on.

I go through the first 7 bullets and they’re all about versions. Well I just installed the latest, I think, so I’m probably OK.

Next there’s something called ipl. What is that? Perhaps it would be good to include a brief description of ipl to say what it is for and why I need it. When I click on the link to gitlab I see, in a big font, DEPRECATED. Why am I here if it is DEPRECATED? Fortunately I read on and found out that it is still needed in Director. Oh, but wait, only for certain versions. Please bullet these points so we don’t have to find the answers in the weeds. I read on because I want to know “WHAT DOES IPL MEAN AND WHAT DOES IT DO” but still it eluded me. I did not see that it tells me that “This module ships the new Icinga PHP library” - oh, there it is. IPL must mean “Icinga PHP library” - but what does it do and where does it fit in the scheme?

OH. Forget what I said before. I went to the link for the currently maintained version of IPL and found a better page. Why send me to the last page at all; all the DEPRECATED info is a waste of github space. I see clearly now: Icinga PHP Library - IPL. Thank you.

Now I want to install the IPL and I see 2 sample “installations”. Nothing explains, for beginners, what to do with what looks like a bash script. I’m not even sure. But I tentatively copy it into my clipboard and paste into the command line:

[root@localhost ~]# INSTALL_PATH="/usr/share/icinga-php/ipl"
[root@localhost ~]# INSTALL_VERSION="stable/0.6.1"
[root@localhost ~]# git clone "$INSTALL_PATH" --branch "$INSTALL_VERSION"
fatal: destination path '/usr/share/icinga-php/ipl' already exists and is not an empty directory.

doh! The clone command choked because I have the lib installed, already.

And I probably have a relatively new ipl dir because I just installed Icingaweb2 2.9.something. But the requirements on this page say requires Icinga Web 2 (>= 2.9) -yes, PHP (>= 5.6, 7+ recommended) -yes, I just installed PHP 7.3.something…

I see a similar install technique used on the IcingaWeb2 Module page; blocks of code which I think are meant to be executed by cut-and-paste into a command line. But never have I seen an explanation of this somewhat disjointed process.

By now, I have spent too much time worrying about IPL (and this post). Now I see I need incubator? and reactbundle? whatever those are. Then a database; can I use what I just installed to get Icingaweb2 running? Then php-curl and other php dependencies which might or might not be installed already.

In general I think the group of developers at Icinga are really smart and thoughtful people, but when it comes to explaining things and how they all fit together, it lacks some… finesse. Now, I must confess, I am NOT the smartest one in the room; ever. So my experience when dealing with your installs is sadly frustrating.

It seems there are too many moving parts in the application and that the tech writers incorrectly assume that end users know what they’re doing.

I was recently setting up docker on one of my KVM instances and it was easier to get that, and portainer, installed and running than Icinga2, Icingaweb2, and well, I am still working on Director (not to mention setting up all the monitoring hosts and services).

While I was playing with portainer I found that an instance of Icinga2/Icingaweb2 was available so I pushed a button and about 2 minutes later, the whole thing was running with Director already installed.

There is some kind of huge disconnect here. Why can’t an application, that is delivered in a container, be delivered in a VM with the same simplicity and speed? I spend all this time installing and configuring when what I really want to do is automate the discovery of my hundreds of servers and their services, apply metric limits for alerting, and have it notify me only when it is meaningfully appropriate. That, and more time for hobbies and sleep. :wink:

1 Like

Using the installation docs from github (for director) might provide better results:

I think there’s still a small disconnect in the documentation there, since IPL moved to another repo, but only if you’re on Icingaweb2 v.2.9.0 or higher (if you click on the IPL link within the above documentation you’ll see this on their github)

Also, IPL is “Icinga PHP Library”.

For Reactbundle and Incubator, (who also have directions on their github repos), you’ll likely want to change the MODULE_VERSION variable in their install directions to match the version that you need for your version of Director (ie, different Director versions require different module versions).

Personally, I have only had small problems using the install directions for Director (and submodules), those problems being getting PHP and the required PHP packages setup correctly, and from time to time an issue because a module documentation hasn’t been updated for the newest version (hence the check).

Also for “just testing” Icinga-Vagrant seems to have everything you need out of the box. Yesterday I found that the Hyper-V provider support I added last year doesn’t work, but haven’t tried it with another supported provider yet (it could also be that something is wrong with my new vagrant setup).

Not that yo need Hyper-V support, but it does have libvirt provider support as well.

Also looks like they have a docker image they support, that takes in a comma separated list of enabedModules (you could try the director module and dependencies in that list). (worth noting that this is only Icingaweb2, but they have docker-icinga2 as well).

Thank you, Ben. I appreciate your patient response. I already have the VM approach in a small KVM server in my laundry room. It works quite well for all my experiments; latest being centos 8 stream with the Icinga apps.

My general point, perhaps expressed in too many words, was that I find it difficult to process through their instructions. They assume I’m an expert. I do linux infrastructure work with terraform and ansible. I monitor them with Icinga, and Icinga web, and graphite/grafana, and pagerduty. But I feel like a moron when it comes to installing Icinga director. I haven’t even gotten to what I think will be the hard part, actually re-defining the hundreds of checks I currently use. An example: The end of Director install instructions ends with:

Either way you’ll reach the kickstart wizards. Follow the instructions and you’re all done!

That is very optimistic. The first thing I encounter is the question about an endpoint and a cert. Wait, what? Did I create an endpoint, or a cert? I think I need to go back through the install instructions.

OK. I went through the pages I followed for Icinga2 installation and IcingaWeb2 installation and I did not find any instance of the word endpoint.

Now! I find a reference to "certificates’ in the “Setting Up Icinga 2 REST API”. I remember running icinga2 api setup and then finding the file, /etc/icinga2/conf.d/api-users.conf, into which I added a second user as directed. I see nothing about endpoints. Or the location of the certs that I think were created in the cli command.

Doing some google search, I see I am not the first to ask this. The answer is: “the endpoint name is typically the same as the host’s FQDN.” - why not say that in the in-page note.

But that does raise an issue for me because I created this instance quickly with a dhcp address and I don’t yet have a meaningful host name. It still thinks it is localhost. I need to do some house cleaning and set up a registered IP in my dhcp server.

But again, Ben. Thank you.