NAME

spong-message - alert the humans when there is a problem


SYNOPSIS

spong-message [--debug] color host service time message [duration]


DESCRIPTION

spong-message is run when there is a problem reported to spong. The following arguments must be given to spong-message.
    * color           color of the message (red, yellow, green)

    * host            host having a problem

    * service         service having a problem

    * time            time (in time() format) of the problem

    * message         summary of the problem
The following parameters are optional.
    * duration        duration of the event in seconds. Default to zero.
When spong-message is called, the information passed in is run through a list of rules which determine who is contacted, when they are contactd and how often.  the information is also run through a number of checks to determine if the message should be sent. It maintains a little database in the spong tmp directory so that it can keep track of how many pages have been sent, when was the last page sent, etc. These checks help to direct problems to the correct people, and also help to throttle messages when there are wide-spread problems (such as a networking outage).

If you are going to be performing maintainence on a machine, or have standard down time for a machine, you can specify that down time in the spong.hosts file. If a problem is reported during the time indicated, spong-message will not send messages.  spong-message also checks for acknowledgements created for a machine. If an active acknowledgement for a machine and service, no messages will be sent.

spong-message using the humans defined in the contact attributes of the messaging rules of spong.mesaage and spong.hosts to determed who is to be contacted. A of contacts is generated from all of the message rules that are matched. The format of thse files is described briefly below, and in more detail in spong.message and spong.hosts.

Currently, spong-message knows how to alert people via the messaging function modules that are installed. More messaging functions can be created. See Message Modules in the Developer Guide.


CONFIGURATION

The most important information (to spong-message anyway) comes from the /usr/local/etc/spong/spong.hosts file. This file defines attributes for two things, 1) the hosts that spong is monitoring, and 2) the humans that are responsible for the various hosts. and how to contact them.

Each host has one ``human'' contact (actually the contact can be a group of people, or really anything you want). Each human has the following attributes:

Each human that is defined should have the following attributes associated with it:

    * name          name of the person to contact
And one or more of the following attributes assigned to each human for messaging when there are problems
 
    * email             email address

    * skytel            skytel pager number

    * alltelsms         phone number of a phone subscribered to Alltel Communications SMS service.

    * teletouch         teletouch pager number

    * teletouch_short   teletouch pages numer for small alpha pagers
The messaging attributes are optional, but at least one must be provided in order to the spong-message program to contact the person. The format of the spong.hosts file is described in more detail in spong.hosts.

Each host also has attributes which are of interest to spong-message. Each host can have the following attribute:

    * down      a list of times the machine is down for repairs.
If the spong-message gets told to send a message during this downtime the message will be ignored. This prevents you from being flooded with messages during routine system maintenence.

The spong.message hold the rules that determine who is to be contacted, when and how often.

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 host groups to match

    * services           a list of services to match

    * exclude_hosts      a list of hosts to exclude

    * exclude_host_groups      a list of hosts groups to exclude

    * exclude_services   a list of services 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 rule alow you to be quite flexible is how your notifications are created. The format if the spong.message if described in more detail in spong.message.
 

The /usr/local/etc/spong/spong.conf file is also read on startup. This file contains some variables specific to spong-message, and some OS specific variables that are required by spong-message. Here are the variables applicable to the spong-message program.

$SEND_MESSAGE
$SEND_MESSAGE defines when spong-message is called by spong-server. It is not really specific to spong-message, but I think it is useful to describe its behavior here. This variable can contain one of four valid values. If it is ``RED'', then spong-message is called for every time a system or service reports a problem. If its value is ``CHANGE'', then spong-message is only called when there is a change of state . If this values is "RED-CHANGE", then spong-message is called  everytime a system of service reported a problem and when the condition is cleared. (going from green/yellow to red, and then again going from red to green/yellow). If its value is ``NONE'', then spong-message is never called.
$MESSAGE_PER_HOUR
This is the maximum number of messages that are sent to the same person in an hour. All message past this number are just logged to the history file, but are not sent. This helps to prevent against message overload such as when you have a networking problem, and everything appears to go red at once. The default value is 5.
$IDENT_MESSAGES_PER_HOUR
This is the maximum number of identical messages that are sent to the same person in an hour. The default value is 3.
$SENDMAIL
These variables are OS specific variables, which are hopefully set correctly for your machine, if they are not - please send me email letting me know what OS you are running on, and what the correct value should be.

EXAMPLES

Here are some lexamples to show you possible configurations.
 %HUMANS = (

  'unix-staff' =>    { name  => 'Midrange On-call Staff',

                       email => 'its-unix@school.edu' },
                      

  'edhill' =>        { name  => 'Ed Hill',

                       email => 'ed-hill@school.edu',

                       skytel => '1234567' },

 );

 %HOSTS = (

  'strobe.weeg.school.edu' =>    { services => 'ftp smtp http',

                                   down     => [ "*:05:30-06:30",

                                                "0:00:00-04:00 ] },

  'www.school.edu' =>            { services => 'ftp smtp http',  },

 );


From spong.message:
  $RULES_MATCH = 'FIRST-MATCH';
  $MESSAGING_RULES = [
      { hosts => [ 'strobe.weeg.school.edu' ],
        contacts => [ 'unix-staff'],
       },
       { hosts => ['www.school.edu'],
         contacts => [ 'edhill:email', { rcpt=>'edhill:pager', repeat=>900, }, ],
       },
  ];

FILES

/usr/local/etc/spong/spong.conf
Configuration file. This contains variables that detail spong and OS specific definitions used by spong-display. See spong.conf for additional documentation.
/usr/local/etc/spong/spong.hosts
Host and human configuration file. This defines what hosts you are monitoring, and what human you should contact if there is a problem. See spong.hosts for additional documentation.
$SPOMGTMP/message-db
Database where information about who has been paged, when, how, and what the problem was is kept.

 
/usr/local/etc/spong/spong.message
Configuration file. This defined the rules on who is to be notified about where, hen and how often. See spong.message for additional documentation.

DEPENDENCIES

Perl v5.003 or greater is required.

To receive pages, you currently must have a pager that can be contacted electronically (via email or web interface).


BUGS

This program currently will only notify via email, so if your pager does not have an email (or TCP accessible) interface - this currently won't work (well won't page) for you.

The $MESSAGES_PER_HOUR check does not always work correctly. The syntax of the contact attribute in spong.message  has changed. The check logic will have to be enhance to be able to check for mulitple forms of the contact.


SEE ALSO

the spong-server manpage , spong.hosts, spong.conf, spong.message


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).