From a0eec0f491801ece50cffbd917e2401a972eefe4 Mon Sep 17 00:00:00 2001
From: Stephen L Johnson <sjohnson@monsters.org>
Date: Mon, 15 May 2000 03:28:30 +0000
Subject: [PATCH] Correcting spelling errors.

---
 src/spong-client.pl  |  37 +++---
 src/spong-message.pl | 281 ++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 300 insertions(+), 18 deletions(-)

diff --git a/src/spong-client.pl b/src/spong-client.pl
index 8a168aa..c5fac20 100755
--- a/src/spong-client.pl
+++ b/src/spong-client.pl
@@ -326,10 +326,13 @@ df output, or a listing of the top 10 processes sorted by CPU.
 =head2 Running the program
 
 You should start this program in your system startup file, and it should be
-running constantly. If you provide the B<--debug> I<n> flag, then debugging
-information will be printed to stdout, otherwise output will only be produced
-if there is a problem. Where I<n> is a number from 1 - 9. A higher number means
-more verbosity in the debugging output.
+running constantly. If no parameters are specified, B<spong-network> forks
+and detaches itself to run as a daemon.
+
+If you provide the B<--debug> I<n> flag, then debugging information will be
+printed to stdout, otherwise output will only be produced if there is a
+problem. Where I<n> is a number from 1 - 9. A higher number means more
+verbosity in the debugging output.
 
 If you provide the B<--restart> flag, a signal will be sent to the spong-client
 process that is currently running that will cause it to reload it's
@@ -343,10 +346,10 @@ module.
 
 =head2 Configuration Files
 
-By default this reads the L<spong.conf|spong.conf> file on startup. You can specify an
-alternate config file via a command line option and it will read that file
-instead. If you change values in the configuration file you will need to
-restart this program for those changes to be re-read.
+By default this reads the L<spong.conf|spong.conf> file on startup. You can
+specify an alternate config file via a command line option and it will read
+that file instead. If you change values in the configuration file you will need
+to restart this program for those changes to be re-read.
 
 After reading the configuration file that you specify (or the default),
 it then reads the F<spong.conf.[hostname]> file where [hostname] is the
@@ -466,13 +469,13 @@ me know what OS you are running on, and what the correct value should be.
 =head2 Client Checks
 
 The checks are actually a set of modules that are called in series by
-spong-client. The list of modules to run are defined in the I<$CHECKS>
+B<spong-client>. The list of modules to run are defined in the I<$CHECKS>
 configuration variable. Upon initialization, B<spong-client> will load the
 modules defined in I<$CHECKS> from the F<LIBDIR/Spong/Client/plugins/>
 directory. As each modules is initialized, it registers itself with the the
-plugins registery (see the L<Developer Guide|developer-guide>. Spong comes with
-a standard set of client checks, see L<Client Modules|client-modules> for
-a more information.
+plugins registery (see the L<Developer Guide|developer-guide>). Spong comes
+with a standard set of client checks, see L<client-modules> for more
+information.
 
 =head2 Extending Functionality
 
@@ -488,7 +491,7 @@ what you have found to the spong server.
 
 =head1 FILES
 
-F</usr/local/etc/spong/spong.conf>, F</usr/local/etc/spong.conf.hostname>
+F<spong.conf>, F<spong.conf.[hostname]>
 
 =head1 EXAMPLES
 
@@ -506,12 +509,12 @@ None know bugs.
 
 =head1 SEE ALSO
 
-L<spong-server>, F<spong.conf>, F<client-modules>, L<developer-guide>,
-L<client-modules> 
+L<spong-server>, F<spong.conf>, F<client-modules>, L<developer-guide>
 
 =head1 AUTHOR
 
-Ed Hill <F<ed-hill@uiowa.edu>>, Unix System Administrator, The University of Iowa
+Ed Hill <F<ed-hill@uiowa.edu>>, Unix System Administrator, The University of
+Iowa
 
 Stephen L Johnson <F<sjohnson@monsters.org>>
 
@@ -520,5 +523,5 @@ Stephen L Johnson <F<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 develop until version
-2.1. Stephen L Johnson tool over development in October, 1999 with his changes
+2.1. Stephen L Johnson took over development in October, 1999 with his changes
 which became Spong 2.5.
diff --git a/src/spong-message.pl b/src/spong-message.pl
index 1dd253a..a42518c 100755
--- a/src/spong-message.pl
+++ b/src/spong-message.pl
@@ -1,4 +1,25 @@
 #!@@PERL@@
+
+=head1 NAME
+
+B<spong-message> - send out alerts when there is a problem
+
+=head1 SYNOPSIS
+
+B<spong-message> [B<--debug>] I<color> I<host> I<service> I<time> I<message> 
+
+=head1 DESCRIPTION
+
+This program is called by the L<spong-server> to send out alerts.  The
+L<spong-server> only makes a quick determination for send out alerts. It's only
+criteria is a change in status of a service. The B<spong-message> make a more
+thorough determination of transmitting the alerts according to the message
+rules defined in the L<spong.messages> configuration file. B<spong-message>
+also has throttling mechanisms to prevent an excessive number of messages from
+being send within a short amount of time.
+
+=cut
+
 #
 # Spong messaging program.  This script gets called when something that spong
 # is monitoring goes red.  This script then runs through a number of tests
@@ -20,7 +41,6 @@ use Spong::AckList;
 
 use Sys::Hostname;
 use English;
-use Data::Dumper;
 
 if( $ARGV[0] eq "--debug" ) { $debug = 1; shift @ARGV; }
 if( $ARGV[0] eq "--test" ) { $test = 1; shift @ARGV; }
@@ -690,3 +710,262 @@ sub save_data {
 }
 
 
+__END__
+
+=head2 Options
+
+The following arguments must be given to B<spong-message>:
+
+=over
+
+=item color
+
+the status color of the message (B<red>, B<yellow>, or B<green>)
+
+=item host
+
+the hostname being of the alart
+
+=item service
+
+the name of the service of the alert
+
+=item time
+
+the date/time (in time() format) of the problem
+
+=item message
+
+a summary line of the problem
+
+=back
+
+=head2 Theory of Operation
+
+When B<spong-message> is called, the information passed in the arguments is run
+through a list of rules which determine who is contacted, when they are
+contacted and how often. The information is also run through a number of checks
+to determine if the message should be sent. 
+
+A small database in the L<$SPONGTMP|spong.conf/"$SPONGTMP"> directory is kept
+so that B<spong-message> can keep track 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
+using the L<down|spong.hosts/"down"> attribute in a
+L<%HOSTS|spong.hosts/"%HOSTS"> variable. If a problem is reported during the
+time indicated, B<spong-message> will not send any messages.
+
+B<spong-message> also checks for any L<acknowledgementas|spong-acks> active for
+a machine. If there an active acknowledgement found for a machine and service,
+no messages will be sent.
+
+B<spong-message> uses the L<%HUMANS|spong.hosts/"%HUMANS"> entries defined in
+the L<contacts|spong.message/"contacts"> attributes of the messaging rules of
+L<spong.message> to determine who is to be contacted. A list of contacts is
+generated from all of the message rules that are matched. (See the
+L<spong.message> and L<spong.hosts> documentation for information on the file
+formats.)
+
+=head2 Messaging Modules
+
+B<spong-message> alerts people via the messaging modules that are installed.
+New messaging functions can be easily created.  See the L<Message
+Modules|developer-guide/"Messaging Modules"> section in the I<Developer Guide>.
+
+=head2 Configuration Files
+
+=over
+
+=item spong.hosts
+
+F<spong.hosts> defined attributes for two things of important to <spong-message>
+1) the hosts that B<Spong> is monitoring (I<%HOSTS>), and 2) the contacts that
+are responsible for the various hosts and how to contact them (I<%HUMANS>).
+
+See L<spong.hosts> for a full description of all of the file formats.
+
+=item spong.message
+
+This file hold the rules that determine who is to be contacted, when and how
+often. There are some of the important configuration variables in the
+F<spong.message> file 1) how the messaging rules are to be scanned 
+(L<$RULES_MATCH|spong.message/"$RULES_MATCH">) and 2) the messaging rules
+(L<$MESSAGING_RULES|spong.message/"$MESSAGING_RULES">)
+
+=back
+
+=head2 Configuration Varirables
+
+From F<spong.hosts>:
+
+=over 
+
+=item %HUMANS
+
+The I<%HUMANS> configuration variable hold all of possible message recipients
+(the humans) and the information necessary on how to contact them.  Each
+I<human> contact can be a person, a group of people, or really anything you
+want. 
+
+Each I<human> that is defined should have I<name> attribute associated
+with it. I<name> is the name or description of the contact. 
+
+To send out any notifications at least messaging attribute must be
+define for the human. A messaging attribute consists of a message module
+name as a key and contact information as a value. See L<"EXAMPLES"> for a
+detailed I<%HUMANS> example.
+
+=item %HOSTS
+
+The I<%HOSTS> configuration variables can hold a list of regularly scheduled
+maintenance periods (I<down>) for each host. Any alerts that are generated
+during a maintenance period will be silently discarded.
+
+=back
+
+From F<spong.message>:
+
+=over 
+
+=item $RULES_MATCH
+
+L<$RULES_MATCH|spong.message/"$RULES_MATCH"> determines how the rules in
+L<$MESSAGING_RULES|spong.message/"$MESSAGING_RULES"> are scanned.  If it is
+I<FIRST_MATCH> the rules will be scanned until the first rule that matches the
+messaging criteria. A value of I<ALL> means that all of the rules are scan with
+the contacts of all matching rules being adding into the list of contacts to
+notify. If the value is I<OLD>, then spong-message will fall back to the
+messaging code used in Spong versions 2.0 - 2.1 for compatibility.
+
+=item $MESSAGING_RULES
+
+L<$MESSAGING_RULES|spong.message/"$MESSAGING_RULES"> contains the rules that
+how, who and how often contacts are notified. See L<$MESSAGING_RULES|spong.message/"$MESSAGING_RULES"> for the full rules syntax.
+
+=back
+
+From F<spong.conf>:
+
+=item $SEND_MESSAGE
+
+L<$SEND_MESSAGE|spong.conf/"$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 I<RED>,
+then B<spong-message> is called for every time a system or service
+reports a problem. If its value is I<CHANGE>, then B<spong-message> is only
+called when there is a change of state . If this values is I<RED-CHANGE>, then
+B<spong-message> is called everytime a service or service reports 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 I<NONE>, then B<spong-message>
+is never called.
+
+=item $MESSAGES_PER_HOUR
+
+L<$MESSAGES_PER_HOUR|spong.conf/"$MESSAGES_PER_HOUR"> 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.
+
+=item $IDENT_MESSAGES_PER_HOUR
+
+L<$IDENT_MESSAGES_PER_HOUR|spong.conf/"$IDENT_MESSAGES_PER_HOUR"> is the
+maximum number of identical messages that are sent to the same person in an
+hour. The default value is 3.
+
+=back
+
+=head1 FILES
+
+=over 
+
+F<spong.conf>, 
+F<spong.hosts>,
+F<$SPOMGTMP/message-db>,
+F<spong.message>
+
+=head1 EXAMPLES
+
+Here are some examples to show you possible configurations.
+
+=over 
+
+=item spong.conf
+
+   %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' },
+
+   );
+
+
+=item 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:skytel', repeat=>900, }, ]
+       },
+
+    ];
+
+=back
+
+
+=head1 DEPENDENCIES</h1>
+
+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).
+
+
+=head1 BUGS
+
+No know bugs.
+
+=head1 SEE ALSO
+
+L<spong-server>, L<spong.hosts>, L<spong.conf>, L<spong.message>,
+L<messaging-modules>
+
+=head1 AUTHOR
+
+Ed Hill <F<ed-hill@uiowa.edu>>, Unix System Administrator, The University of
+Iowa
+
+Stephen L Johnson <F<sjohnson@monsters.org>>
+
+=head1 HISTORY
+
+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 develop until version
+2.1. Stephen L Johnson took over development in October, 1999 with his changes
+which became Spong 2.5.
-- 
2.30.2