NAME

spong.message - define rules on how and when to send messages


DESCRIPTION

The spong.message file defines the rules that spong-messge program used for notifications. The rules consist of attributes which define crieria which events are matched against and a list of contacts to notifiy if all of the matching criteria are met.

Each rule should have more of more of the following matching criteria attributes:

    * hosts              a list of hosts to match

    * host_groups        a list of hosts groups to match

    * services           a list of services to match

    * exclude_hosts      a list of hosts to exclude

    * exclude_services   a list of services to exclude

    * exclude_host_groups   a list of host groups to exclude

    * times              a list of days/times to match
And each rule must have the following attributes:
    * contacts           a list of contacts to notify
The hosts are a list of host names that are matched against the host name parameter passed to spong-message.

The services are a list of services that are matched against the service parameter passwd to spong-message.

The exclude_hosts are a list of host names that are be excluded from matching the rule.

The exclude_services are a list of services that are to be excluded from matching the rule.

The times are a list of stanzas the have days of the week and/or time ranges to match against the time parameter passed to spong-message. Each times stanza can have a days and/or a times attribute which are lists of days and times ranges to be matched.

The days attribute 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=Staurday). And 'd-'d represents a range of days (i.e. 1-5 = Monday - Friday).

The times attribute 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.

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 who groups of hosts or services to match.

The down attribute is a list of ``downtimes''. It is a list (well reference to one anyway) of one or more strings in the following format - ``d:hh:mm-hh:mm''. ``d'' is the day of the week (0-6, 0 = Sunday, 6 = Saturday), if ``d'' is ``*'', then every day of the week is matched. The string to the right of the day is the start and end time of the down time in 24 hour format

The contacts is a list of stanzas representing the contacts to notify if the all of the rules' matching criteria are met. Each stanza can be a string or a contact stanza.  The strings can be one of the following formats - 'human' or 'human:func' where human is a strings represent an entry from the %HUMANS defined in spong.hosts and func is one of the message functions attributes defined for that human.

A contact stanza can must have a rcpt attribute which is a strings are defined above. It can optiionally can have a delay and/or a repeat attributes. The delay attribute is the duration, in seconds, that an event must have before the rcpt is notified. The repeat is the time interval, in seconds, in which notifications are resent once an initial notification is sent.


FORMAT

The spong.message file is simply Perl code that gets imported by each spong 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 },
                    { rcpt=>'the_boss', delay=>7200, repeat=>3600 },
                   ],
    },
The $RULES_MATCH variable has three possible values: OLD - Use Spong ver 2.1 messaging. Send notification the human defined in the contact attibute for the host name of the message. FIRST-MATCH - Rules are checked in order until the first one that matches. ALL - Rules are checked into order. All rules that match are processed.

I know the format can be a little odd 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.


MATCHING LOGIC

The primary factor of how spong.message rules are processed depends upon the vaule 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 behaviour. Notify the human defined in the contact attribute of the %HOSTS entry for the host. If set to 'FIRST-MATCH' then the rules are check in order until the first rule matching the event parameter is. spong-message will then begin notification processing. If $RULES_MATCH is set to 'ALL' then al of the rules are scan in order. The contacts of all matching rules are adding to the list of  recipients that will be notified.

All of the matching attributes except for exclude_hosts and exclude_services 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 and exclude_services have a slightly different matching behaviour man the other matching attributes, if there is a match against either of them, the rule will not match even if all of the other matching attreibute 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 attribute's subattribues, days and times , have the automatic match if absent property. If one of the sub-attributes is missing from a stanza any check against that attribute will succeed. That is days is missing from the stanza, any day of the week will match againast the stanza. If the times sub-attribute is missing, the stanza matches against any time.  A times attribute match succeeds if any stanza of the attribute matches.


EXAMPLES

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'],
        },

        # Let Dwayne in Engineering know when a system does down and dns problems 
        # except for the test box
        {
                hosts => ['.*'],
                services => ['ping','ftp','smtp','dns'],
                exclude_hosts   => ['tunixt'],
                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
        {
                hosts => ['.*.k12.ar.us'],
                services => ['.*'],
                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'] },
                        ],
        },

  ];


COMPATABILITY

To use Spong version 2.1 message and messaging configurations set $RULES_MATCH to 'OLD'. If $RULES_MATCH is not defined it will default to 'OLD'.

SEE ALSO

the spong-message manpage


AUTHOR

Ed Hill (ed-hill@uiowa.edu), Unix System Administrator, The University of Iowa
Stephen L Johnson (stephen.johnson@mail.state.ar.us) or (sjohnson@monsters.org), Unix System Administator, DIS - State of Arkansas

Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong).