--- /dev/null
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <meta name="GENERATOR" content="Mozilla/4.61 [en] (X11; U; Linux 2.2.12-20 i686) [Netscape]">
+ <title>spong-message</title>
+</head>
+<body>
+
+<hr>
+<h1>
+<a NAME="spong-message_name_0"></a>NAME</h1>
+<b>spong-message</b> - alert the humans when there is a problem
+<p>
+<hr>
+<h1>
+<a NAME="spong-message_synopsis_0"></a>SYNOPSIS</h1>
+<b>spong-message</b> [--debug] color host service time message [duration]
+<p>
+<hr>
+<h1>
+<a NAME="spong-message_description_0"></a>DESCRIPTION</h1>
+spong-message is run when there is a problem reported to spong. The following
+arguments must be given to spong-message.
+<pre> * 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</pre>
+The following parameters are optional.
+<pre> * duration duration of the event in seconds. Default to zero.</pre>
+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).
+<p>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.
+<p>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 <i>spong.message</i> and <i>spong.hosts</i>.
+<p>Currently, spong-message knows how to alert people via the messaging
+function modules that are installed. More messaging functions can be created.
+See <b><a href="developer-guide.html#message-modules">Message Modules</a></b>
+in the <a href="developer-guide.html">Developer Guide</a>.
+<p>
+<hr>
+<h1>
+<a NAME="spong-message_configuration_0"></a>CONFIGURATION</h1>
+The most important information (to spong-message anyway) comes from the
+<a href="spong-message.html#spong-message_usr_local_etc_spong_spong_hosts_0">/usr/local/etc/spong/spong.hosts</a>
+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.
+<p>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:
+<p>Each human that is defined should have the following attributes associated
+with it:
+<pre> * name name of the person to contact</pre>
+And one or more of the following attributes assigned to each human for
+messaging when there are problems
+<br>
+<pre> * 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</pre>
+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 <i><a href="spong_hosts.html">spong.hosts</a></i>.
+<p>Each host also has attributes which are of interest to spong-message.
+Each host can have the following attribute:
+<pre> * down a list of times the machine is down for repairs.</pre>
+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.
+<p>The <i>spong.message</i> hold the rules that determine who is to be
+contacted, when and how often.
+<p>Each rule should have more of more of the following matching criteria
+attributes:
+<pre> * 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</pre>
+And each rule must have the following attributes:
+<pre> * contacts a list of contacts to notify</pre>
+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 <i><a href="spong-message.html">spong.message</a></i>.
+<br>
+<p>The <a href="spong-message.html#spong-message_usr_local_etc_spong_spong_conf_0">/usr/local/etc/spong/spong.conf</a>
+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.
+<dl>
+<dt>
+<a NAME="spong-message_send_message_0"></a><b>$SEND_MESSAGE</b></dt>
+
+<dd>
+<a href="spong-message.html#spong-message_send_message_0">$SEND_MESSAGE</a>
+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 <b>spong-message</b> is called for every time a system or service
+reports a problem. If its value is ``CHANGE'', then <b>spong-message</b>
+is only called when there is a change of state . If this values is "RED-CHANGE",
+then <b>spong-message</b> 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 <b>spong-message</b> is never called.</dd>
+
+<dt>
+<a NAME="spong-message_message_per_hour_0"></a><b>$MESSAGE_PER_HOUR</b></dt>
+
+<dd>
+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.</dd>
+
+<dt>
+<a NAME="spong-message_ident_messages_per_hour_0"></a><b>$IDENT_MESSAGES_PER_HOUR</b></dt>
+
+<dd>
+This is the maximum number of identical messages that are sent to the same
+person in an hour. The default value is 3.</dd>
+
+<dt>
+<a NAME="spong-message_sendmail_0"></a><b>$SENDMAIL</b></dt>
+
+<dd>
+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.</dd>
+</dl>
+
+<hr>
+<h1>
+<a NAME="spong-message_examples_0"></a>EXAMPLES</h1>
+Here are some lexamples to show you possible configurations.
+<pre> %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:</pre>
+
+<pre> $RULES_MATCH = 'FIRST-MATCH';</pre>
+
+<pre> $MESSAGING_RULES = [</pre>
+
+<pre> { hosts => [ 'strobe.weeg.school.edu' ],</pre>
+
+<pre> contacts => [ 'unix-staff'],</pre>
+
+<pre> },</pre>
+
+<pre> { hosts => ['www.school.edu'],</pre>
+
+<pre> contacts => [ 'edhill:email', { rcpt=>'edhill:pager', repeat=>900, }, ],</pre>
+
+<pre> },</pre>
+
+<pre> ];</pre>
+
+<hr>
+<h1>
+<a NAME="spong-message_files_0"></a>FILES</h1>
+
+<dl>
+<dt>
+<a NAME="spong-message_usr_local_etc_spong_spong_conf_0"></a><b>/usr/local/etc/spong/spong.conf</b></dt>
+
+<dd>
+Configuration file. This contains variables that detail spong and OS specific
+definitions used by spong-display. See <i><a href="spong.conf.html">spong.conf</a></i>
+for additional documentation.</dd>
+
+<dt>
+<a NAME="spong-message_usr_local_etc_spong_spong_hosts_0"></a><b>/usr/local/etc/spong/spong.hosts</b></dt>
+
+<dd>
+Host and human configuration file. This defines what hosts you are monitoring,
+and what human you should contact if there is a problem. See <i><a href="spong_host.html">spong.hosts</a></i>
+for additional documentation.</dd>
+
+<dd>
+</dd>
+
+<dt>
+<b><i>$SPOMGTMP/message-db</i></b></dt>
+
+<dd>
+Database where information about who has been paged, when, how, and what
+the problem was is kept.</dd>
+
+<br>
+<dt>
+<b>/usr/local/etc/spong/spong.message</b></dt>
+
+<dd>
+Configuration file. This defined the rules on who is to be notified about
+where, hen and how often. See <i><a href="spong_message.html">spong.message</a></i>
+for additional documentation.</dd>
+</dl>
+
+<hr>
+<h1>
+<a NAME="spong-message_dependencies_0"></a>DEPENDENCIES</h1>
+Perl v5.003 or greater is required.
+<p>To receive pages, you currently must have a pager that can be contacted
+electronically (via email or web interface).
+<p>
+<hr>
+<h1>
+<a NAME="spong-message_bugs_0"></a>BUGS</h1>
+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.
+<p>The <b>$MESSAGES_PER_HOUR</b> check does not always work correctly.
+The syntax of the contact attribute in <i>spong.message<b> </b></i>
+has changed. The check logic will have to be enhance to be able to check
+for mulitple forms of the contact.
+<br>
+<hr>
+<h1>
+<a NAME="spong-message_see_0"></a>SEE ALSO</h1>
+the <i>spong-server</i> manpage , <i>spong.hosts</i>, <i>spong.conf, spong.message</i>
+<p>
+<hr>
+<h1>
+<a NAME="spong-message_author_0"></a>AUTHOR</h1>
+Ed Hill (<a href="MAILTO:ed-hill@uiowa.edu">ed-hill@uiowa.edu</a>), Unix
+System Administrator, The University of Iowa
+<br>Stephen L Johnson (<a href="MAILTO:stephen.johnson@mail.state.ar.us">stephen.johnson@mail.state.ar.us</a>)
+or (<a href="MAILTO:sjohnson@monsters.org">sjohnson@monsters.org</a>),
+Unix System Administator, DIS - State of Arkansas
+<br>
+<p>Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong).
+</body>
+</html>
projects / spong.git / commitdiff