From: Stephen L Johnson Date: Mon, 15 Nov 1999 06:22:02 +0000 (+0000) Subject: Initial import X-Git-Tag: start~20 X-Git-Url: http://git.etc.gen.nz/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=55d12ee5a9a02971ee9a07a37798f77438bec7a1;p=spong.git Initial import --- diff --git a/www/docs/spong-message.html b/www/docs/spong-message.html new file mode 100755 index 0000000..c152a2f --- /dev/null +++ b/www/docs/spong-message.html @@ -0,0 +1,286 @@ + + + + + + spong-message + + + +

+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
+
+    * services           a list of services to match
+
+    * exclude_hosts      a list of hosts 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). + +