================================================================
NAGIOS AGGREGATE NOTIFICATION SYSTEM: README
================================================================
(c) 2001 - Nicholas Tang (ntang at nachtwache dot org)
Updated - Bob Patterson (bobpattersonjr at gmail dot com)
Under the Gnu Public License v2.0
http://www.gnu.org/copyleft/gpl.txt
----------------------------------------------------------------
INTRODUCTION
The Nagios Aggregate Notification System (NANS) is designed to
replace the existing 1-line shell script that currently handles
notifications in Nagios (http://www.nagios.org/). It is a
drop-in replacement that doesn't require any changes to the
existing Nagios configuration other than telling it to use NANS
instead of the current system. It is configurable on per-contact
basis and allows for different levels of aggregation for epager
vs. email notifications.
It was designed to cut back on the flood of notifications that can
occur at a larger Nagios installation; I have personally had as
many as 13 pages get sent to me in a one minute period when we had
a problem on the network, and unfortunately not every service or
host can easily be assigned a parent - and even if it has one, until
Nagios notices the parent is unavailable, it will still report a
problem with the children.
The latest version should always be available from my homepage at
http://www.nachtwache.org/projects/ (under nagios/ utilities/
nans/ most likely).
----------------------------------------------------------------
INSTALLATION
(Note: if upgrading from an old version, skip down to the next
section, cunningly labelled "UPGRADING".)
Installation is a simple matter. First off, put the two scripts
(aggregate-notify.pl and collate-notifications.pl) on your system -
I use Nagios's bin directory since it's mostly empty. They can
go anywhere, as long as the Nagios user has read/execute privs
for them.
The next step is to create the configuration file(s). You can
have one per instance, or one shared one, or whatever. I use one
shared one, but some places might find it convenient to have
different settings for different situations.
SAMPLE CONFIG FILE
# This is a comment
foo@bar.com,1,0,1,0
billybob@bar.com,1,1,0,1
The example above will give user foo the count and summary reports,
and give the user billybob the count, mini-summary and detailed reports.
The config file is simple. Lines with a # at the beginning are
comments (note, the "#" must be the FIRST character on the line).
All other lines are considered config lines. I will likely make it
a little more lenient in the next version, but for now, deal. ;)
Each line should have 5 comma-delimited fields (no spaces). The
first field is the contact email address, and fields 2-5 are simple
on/off flags (0=off, 1=on) that determine which types of reports
should be sent for that contact: a simple count, a mini summary,
a more detailed summary, or the full details. Note that the summary
and full details are mostly identical in terms of the information
they provide, the summary is simply more compact. The mini summary
is much more compact and strips out more information.
Next, you need to add entries in your crontab for the aggregate
mailer. There are four settings for it:
-t: the frequency, in "time units", to send the emails
-f: the full path to the notification log (generated by the other tool)
-c: the full path to the config file (discussed above)
-g: turns on grouping by host
I say "time units" rather than minutes, because it actually stands
for the number of times it should run before it will actually
send out the notifications. If you run it every minute from cron,
it will be in minutes. Run it every 5 minutes, and a single unit
will be 5 minutes.
Here's an example:
* * * * * /usr/local/nagios/bin/aggregate-notify.pl -t 2 -c '/usr/local/nagios/etc/notification-page.cfg' -f '/usr/local/nagios/var/rw/page-log.txt'
* * * * * /usr/local/nagios/bin/aggregate-notify.pl -t 10 -c '/usr/local/nagios/etc/notification-email.cfg' -f '/usr/local/nagios/var/rw/email-log.txt'
If it's set up correctly, it should create a single-line file
where you specified -f, and that line should be a comment with the
current "ttm" value (time to mail ;) ) and the timer value you set
with -t.
Finally, you need to set up the notification collator. To do this,
you need to configure Nagios to use it instead of the existing script.
Replace the existing notify-by-email, notify-by-epager,
host-notify-by-email, and host-notify-by-epager lines with the
following, modifying the paths to match your install, of course:
define command{
command_name notify-host-by-email
command_line /usr/local/nagios/collate-notifications.pl -t 'HOST' -e '$CONTACTEMAIL$' -d '$LONGDATETIME$' -n '$NOTIFICATIONTYPE$' -I '$HOSTADDRESS$' -H '$HOSTNAME$' -h '$HOSTSTATE$' -o '$HOSTOUTPUT' -A '$HOSTNAME$' -a '$HOSTNAME$' -f '/usr/local/nagios/var/rw/email-log.txt'
}
define command{
command_name notify-service-by-email
command_line /usr/local/nagios/collate-notifications.pl -t 'SERVICE' -e '$CONTACTEMAIL$' -d '$LONGDATETIME$' -n '$NOTIFICATIONTYPE$' -I '$HOSTADDRESS$' -H '$HOSTNAME$' -S '$SERVICEDESC$' -s '$SERVICESTATE$' -o '$SERVICEOUTPUT$' -A '$HOSTNAME$' -a '$SERVICEDESC$' -f '/usr/local/nagios/var/rw/email-log.txt'
}
The only setting you need to adjust is -f, which is the path to the same
file you specified with -f for the aggregator.
Optional:
- In both scripts you can set the $loglevel variable. This variable
determines how verbose the logging should be, from 0 (none) to 4
(ridiculous). If you turn on logging, make sure to also set the
$logfile variable. Of course, if $loglevel is set to 0, that isn't
needed.
- aggregate-notify needs to have the path to sendmail set; if your
sendmail (or whatever mailer) is in a different location make sure
you fix that.
- If you're having problems with the script, set $debug to 1, which
will output all of the errors and such to STDOUT in addition to the
log file. Makes it a bit easier to, well, debug.
- You can now easily define your own output format... well, semi-
easily. No docs are being provided for this part, but if you look
at how %fmt works you should see it. If not, well, ask. :)
----------------------------------------------------------------
UPGRADING
NANS 0.5 -> 0.6
Just as easy as 0.4 to 0.5. There are some optional variables
you can set, but otherwise it's just a drop-in replacement.
One note: it now supports grouping notifications by host. To
do that, simply slap a "-g" on aggregate-notify. It removes
some of the aggregation, so I wouldn't use it everywhere, but
in some situations it can be very useful.
As there's now the potential to easily redefine or define new
output formats, that could potentially change your config file -
but that only affects you if you actually define a new format,
which is really more of an advanced option.
NANS 0.4 -> 0.5
Cakewalk.
- Replace the scripts.
- Optionally, set the $loglevel and $logfile. (See the OPTIONAL
section under INSTALLING.)
NANS 0.3 -> 0.4
Upgrading from NANS 0.3 is a pretty simple task. The only "gotcha" is
making sure you update your config file correctly.
The config file format has changed slightly. The entries in version
0.3 looked like this:
email@address.com,count,summary,full
An entry in 0.4's config file looks like this:
email@address.com,count,minisum,summary,full
I know, you're probably annoyed that I'm changing the order of the fields,
right? I am too, but I figured in the long run it made more sense for the
reports to go from "smallest" to "largest" rather than "first one I wrote"
to "last one I wrote".
I'd recommend making a new config file, say, nans-0.4.conf, and then
editing that. Put the new versions of collate-notifications and
aggregate-notify in place, and that's it. There's been no syntax change
in them, so they can just be dropped in to replace the old ones.
Enjoy!
Nicholas Tang
ntang -at- nachtwache -dot- org
Bob Patterson
bpatterson -at- i1ops dot net