You Lie, Nagios 3.0 documentation!!!

[dev0]

Not sure if this is the appropriate forum, but it seemed the best fit.

I'm going to try to avoid a long spiel, but I wanted to raise the issue of the quality of documentation available for Nagios Core. Specifically, I want to point out one important instance of the documentation being not merely incomplete, but actually misleading, in a way that may be turning users off to the product, or complicating their configurations enormously and unnecessarily.

Long story short: I had set up what seemed to be a logical series of hosts, services, and corresponding groups. All was fine and well, until I tried to customize my service escalations, with each machine hosting two sets of services that needed to notify different groups at differing intervals. I was referring to:

http://nagios.sourceforge.net/docs/3_0/ ... escalation

...as an exhaustive, authoritative source for information on making this happen. That was a mistake that eventually cost me several days of work, some embarrassing e-mail spamming, and multiple ugly configuration reversions. You see, the definition listed for serviceescalation objects is totally inaccurate and substantially misleading. The definition supplied clearly labels both 'host_name' and 'service_description' as required fields. In reality, neither of these is required so long as you specify the UNLISTED(!) servicegroup_name directive, as exampled here, from off in some far-hidden corner of the same documentation set:

http://nagios.sourceforge.net/docs/3_0/ ... ricks.html

...now of course, I could have gone out and defined service escalations uniquely for each of the n services on each of n servers, or some other horrible kludge, but that's what groups are for, right: maximizing configuration reusability. It sure would have been nice to know about the "Object Trick" of using a servicegroup_name in a serviceescalation object before I rewrote the configurations several times while pounding my head against a wall.

tl;dr - Nagios' documentation lied to me about the capabilities of serviceescalation objects, making me look the fool to those on the notification lists and forcing me to repeatedly restructure my configuration files in weird and unnecessary ways to work around a missing directive that isn't actually missing, just undocumented.

[slansing]

The documentation did not "lie" to you, it simply guides you through a method for defining escalations. Sure, they are labeled as required, that is because the method shown there is, shall we say... the standard method. Of course you could use some lesser known / used features of nagios as there are quite a few and they could be used in many places. But, the "servicegroup_name" definition is not required either..

Keep in mind you can always come ask questions here, and this documentation is made for a basic walk through. Also, we recommend disabling notifications or removing contact definitions while playing around with a volatile object's definition. A dummy host / service is a good testing bed.

[dev0]

The documentation did not "lie" to you, it simply guides you through a method for defining escalations.

I'll have to humbly disagree. When the documentation leaves out certain directives entirely, and calls others "required" that are not actually "required"... yea, that's lying to me. I don't intend to ascribe malice to it, the statement is one of graveyard-humorous annoyance, but it is what it is, and what it is is erroneous documentation.

Sure, they are labeled as required, that is because the method shown there is, shall we say... the standard method.

So, in other words, they're labelled incorrectly as "required" when they're actually "recommended" but not "required". Right?

Of course you could use some lesser known / used features of nagios as there are quite a few and they could be used in many places. But, the "servicegroup_name" definition is not required either..

I understand that, but why is such a useful feature hidden/undocumented? The object definitions are supposed to be exhaustive. Is specifying a servicegroup_name inside of a serviceescalation block really a lesser used feature? It seems pretty essential as a way to templatize configurations.

Keep in mind you can always come ask questions here, and this documentation is made for a basic walk through.

That's just... not good enough, sir. Nothing personal, but the documentation I referenced carries no such disclaimers or warnings, and hardly seems made for "a basic walk through". It purports to be a list of definitions of object types. The word "definitions" carries some very specific connotations pertaining to exhaustiveness and correctness.

[scottwilkerson]

I understand that, but why is such a useful feature hidden/undocumented? The object definitions are supposed to be exhaustive. Is specifying a servicegroup_name inside of a serviceescalation block really a lesser used feature? It seems pretty essential as a way to templatize configurations.

While I can understand your frustration, I do need to point out that this "hidden" documentation you are referring to, is the 2nd link in the "See also:" at the very top of the page
http://nagios.sourceforge.net/docs/3_0/ ... escalation

In any event, I will make a recommendation that the documentation make a second reference to this link stating that there are "alternate" required fields outlined in the Object Tricks document