=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
=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
=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
=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
=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>>
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.
#!@@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
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; }
}
+__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.
projects / spong.git / commitdiff