| Next: spongfaq | Previous: spong.hosts | [Table of Contents] | [Index] |
spong.message - define rules on how and when to send notifications
The spong.message file defines the rules that spong-message program used
for notifications. The rules consist of attributes which define criteria
which events are matched against and a list of contacts to notify if all
of the matching criteria are met.
The variable governs the matching rules are processed. The possible values are 'OLD', 'FIRST-MATCH', or 'ALL'.
This functionality will be removed at some point in the future.
Each rule should have more of more of the following matching terms:
spong.groups (see
the spong.groups manpage). The host name of the event check against all of the members
of the specified groups. If it is found, this attribute is considered matched.
spong.groups (see the spong.groups manpage). If the host name of the status event is a member of one of the host
groups, the term is considered an exclusion match.
And each rule must have the following attributes:
Each of the elements of the hosts, services, exclude_hosts, and exclude_services are actually Perl regular expressions. You can use wide cards to specify which groups of hosts or services to match.
The times term is a list of stanzas that have days of the week (days) and/or time ranges (times) to match against the time parameter passed to spong-message. Each times stanza can have a days and/or a times attributes.
The days attributes are a list of strings with the following format - 'd' or 'd-d'. Where d is the day of the where (0-6, 0=Sunday, 6=Saturday). And 'd-d' represents a range of days (i.e. 1-5 = Monday - Friday).
The times attributes are a list of string with the following format - 'hh:mm-hh:mm'. This is a starting and ending time of a time range in 24 hour format.
Note: The down attribute in a host's entry in the spong.hosts file has the effect of an "exclude_times" term for the host. If the timestamp of
a status event matched on a down downtime period, no notifications will
be sent. See the section on down in the spong.hosts manpage for more details.
The contacts term is a list of stanzas representing the contacts to notify
if the rule's matching criteria are met. Each stanza can be
a string or a contact stanza. The strings can be one of the following
formats - 'human', 'human:func' where human is a strings represent an
entry from the %HUMANS defined in spong.hosts
and func is one of the message module attributes defined for that human.
A contact entry can also be a stanza The stanza must have a 'rcpt' attribute which is a contact strings as defined above (i.e. 'human' or 'human:func'). It can also have an optional delay and/or repeat attribute. The delay attribute is the duration, in seconds, that an event be in an alert status before the rcpt is notified. The repeat attribute is the time interval, in seconds, in which notifications are resent once an initial notification is sent.
The spong.message file is simply Perl code that gets imported the spong-message program, so the only real format restrictions is just what is syntactically correct in Perl (which some would say is anything 8-).
What is expected in this file are the definition for the $MESSAGING_RULES
and $RULES_MATCH which determines how the rules are processed. If you are
not comfortable with Perl lingo, then just think of them as stanza definitions.
$MESSAGING_RULES = [ [stanza], [stanza], [stanza] ]
where [stanza] is a second hash, that looks like the following:
{ hosts => [ 'unixweb', '.*-ops.cic.myschool.edu', 'steves-pc' ]
services => [ '.*' ],
exclude_hosts => [ 'backup-ops.cic.myschool.edu'],
exclude_services => [ 'dns', 'ssh'],
times => [
{ days=> ['0','1-3','4-5'],
times=> ['06:30-18:30','21:00-22:00'
},
{ days => ['5','6','0-2'] },
{ times => ['13:00-15:23','00:00-23:39'] },
],
contacts => [ 'ops', 'sjohnson:email',
{ rcpt=>'sjohnson:teletouch', delay=>900, repeat=>600 },
{ rcpt=>'the_supervisor:teletouch', delay=3600,
repeat=>1800 },
# This contact should get be notified or else !!!!!
{ rcpt=>'the_boss', delay=>7200, repeat=>3600 },
],
},
The $RULES_MATCH variable has three possible values:
I know the format can be a little odd at first and overwhelming at first, but I chose it because of both its simplicity to work with in the code (I don't have to parse anything - Perl does all the work), and because it is easy to extend - adding additional attributes is quite straightforward.
Notification messages formats are determined by the templates in the
%TEMPLATES variable in the spong.message file. Templates are searched
according to the following order: 'contact:module', 'module', 'contact',
'DEFAULT'.
Any text in a template string is added verbatim to the message. The list of substitution variables can be added to the template strings.
spong.conf configuration variable.
The primary factor of how spong.message rules are processed depends upon the value of $RULES_MATCH. If set to 'OLD' then the rules are not used at all. spong-message reverts back to it Spong version 2.1 behavior. Notify the human defined in the contact attribute of the <b>%HOST/b entry for the host.
This functionality included for backwards compatibility and to aid in migrating old Spong vers 2.0 and Spong 2.1 installations to the current version. It will be removed some future version of Spong.
If %RULES_MATCH is set to 'FIRST-MATCH' then the rules are check in order until the first rule matching the event parameters. spong-message will then begin notification processing. All of the contacts will be notified and then the program will exit.
If $RULES_MATCH is set to 'ALL' then all of the rules are scan in order. The contacts of all matching rules are adding to the list of recipients that will be notified. After rule matching is finished all of the contacts are be notified.
All of the matching attributes except for exclude_hosts, exclude_services and exclude_host_groups have an automatic "match if absent" property. For example, if the hosts attribute is missing from a rule, that rule will match any host name.
The exclude_hosts, exclude_services, and exclude_host_groups terms have a slightly different matching behavior man the others. If there is a match against any of them, the rule will not match even if all of the other terms match. For example, if a rules has hosts = [ '.*.cic.my-company', '.*.corp.my-company.com' ]> and exclude_hosts[ 'my-pc' ], a host name of 'my-pc.corp.my-company.com' will not match against this rule because of the host name matches the exclude_hosts attribute.
The times term's attributes, days and times , have the automatic "match if absent" property also. If one of the sub-attributes is missing from a stanza any check against that attribute will succeed. That is, if days is missing from the stanza, any day of the week will match against the stanza. If the times attribute is missing, the stanza matches against any time.
Here are some lines from our spong.hosts file to show you possible
configurations.
$MESSAGING_RULES = [
# Franks Notifications
# Let him know about if it has been down for 30 minute or more.
{
hosts => [ '.*' ],
services => [ '.*' ],
contacts => [ {rcpt=>'fsipes', delay=>1800}, ],
exclude_hosts => ['tunixt'],
exclude_services => ['test'],
},
# Please note the previous stanza can also be written as follows
# Both stanzas are equivalent.
{
contacts => [ {rcpt=>'fsipes', delay=>1800}, ],
exclude_hosts => ['tunixt'],
exclude_services => ['test'],
},
# Let Dwayne in Engineering know when a system does down and dns problems
# except for the test box and only send him down messages
{
hosts => ['.*'],
services => ['ping','ftp','smtp','dns'],
exclude_host => ['tunixt'],
exclude_colors => ['green','yellow']
contacts => [ 'dstucker' ],
},
# Let me know about everything except the test box except late at
# night
{
hosts => ['.*'],
services => ['.*'],
exclude_services => ['nntp','ntp'],
exclude_hosts => ['tunixt'],
contacts => ['sjohnson'],
times => [
{ times => ['06:00-21:00'] },
],
},
# Notify the unix oncall pager about the k12 systems after hours
# during week days and anytime on the weekend and repeat them
# every 15 minutes until acknowledged
{
host_groups => [ 'apscn' ],
exclude_services => ['nntp','ntp'],
exclude_hosts => ['tunixt'],
contacts => [ { rcpt=>'unix-oncall:teletouch', repeat=>900}, ],
times => [
{ days => ['1-5'], times => ['17:00-23:59','00:00-08:00'] },
{ days => ['0','6'] },
],
},
];
To use Spong version 2.1 spong-message and messaging configurations set $RULES_MATCH to 'OLD'. If $RULES_MATCH is not defined it will default to 'OLD'.
the spong-message entry elsewhere in this document, the spong.hosts manpage, the spong.groups manpage
Ed Hill <ed-hill@uiowa.edu>, Unix System Administrator, The University of
Iowa
Stephen L Johnson <sjohnson@monsters.org>
Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong). Ed Hill original converted Big Brother (http://www.bb4.com) into Perl which diverged from Big Brother to become Spong. Ed Hill continued Spong development until version 2.1. Stephen L Johnson took over development in October, 1999 with his changes which became Spong 2.5.