To build and install the spong server do the following on the machine
that is to be the Spong Server. It is suggest that your have web server
-running on the same machne for the spong web display program. It is not
+running on the same machine for the spong web display program. It is not
required, but it will simplify the installation.
-=over
+=over 8
-=item o
+=item *
Edit the "build" script, and set the variables at the top of that script
according to where you want spong installed, and where certain programs
that spong relies on are located.
-=item o
+
+=item *
Check to make sure there is a config/spong.conf.E<lt>osE<gt> file corresponding
to your operating system, if not - create one. This file contains paths and
like disk usage, etc... If you have to create your own spong.conf.E<lt>osE<gt>
file, then please email it to me so that I can add it to the distribution.
-=item o
+
+=item *
Make sure you are in the directory that you unpacked spong in and type:
-C<./build E<lt>osE<gt>> where E<lt>osE<gt> is the name corresponding to your
+C<./build <os>> where E<lt>osE<gt> is the name corresponding to your
operating system. You can type C<./build help> to generate a list of
valid operating system strings.
creates a spong.conf file, and generates various types of documentation
based on the POD files that come with spong.
-=item o
+
+=item *
Now, type C<./build install>. Note that the install process makes
no assumptions about what user you want to run spong as (you B<don't>
that you have permission to copy the www pages into your web server's document
tree).
-=item o
+
+=item *
Now edit the spong.conf, spong.hosts, spong.group and spong.messages files
that you just installed and season to taste. You should now be able to
read the manual pages for each.
-=back
+=back
Now you will have the executables and configuration files in place
on the server. You need to start the spong-server and spong-network programs.
files show up in the I<$SPONGDB> directory that you defined in the spong.conf
file.
-B<NOTE - HOSTNAMES:> Part of spong-server's status message authentification has
+B<NOTE - HOSTNAMES:> Part of spong-server's status message authentication has
to do with host names. B<spong-server> checks the host name in a status message
against the hosts defined in the spong.hosts file. The the status message host
name is not found, spong-server will silently drop the messages.
So it is important that your serves are able to resolve their fully qualified
-domain name. To do this check there is a little perl test program
+domain name. To do this check there is a little Perl test program
B<gethost-test> from in the F</utils> directory of the Spong distribution. Just
run it from a command line by entering C<perl gethost-test.> It tests to see is
the host can resolve it's fully qualified domain name. If it can't then it
=head2 Debugging Problems
The general way to debug Spong programs is to use the B<--debug #> parameter.
-The B<#> is a number from 1 to 9 that contols the amount of debugging that is
+The B<#> is a number from 1 to 9 that controls the amount of debugging that is
printed. The higher the number the more detail that is output. This force the
program to run in the fore-ground, (if it daemonizes itself) and the program
will print out a lot of debugging statements. Also each program updates it's
-command line buffer with the current status which can be viewed in the ps
+command line buffer with the current status which can be viewed in the C<ps>
command.
If I<$SPONG_LOG_FILE> or I<$SPONG_LOG_SYSLOG> are set in the F<spong.conf> file
the programs will log errors to a log file and/or syslog , respectively. The
file are named F<program-name.log> in the I<$SPONGTMP> directory and the
-entries are logged to syslog under the USER facility with a priorty of ERR.
+entries are logged to syslog under the USER facility with a priority of ERR.
=over
fore-ground and all of the child processes with write their debugging
statements to the screen. The I<query> processing will print out all of the
database queries with the type of data requested and in what format. The
-I<spong update</i> and I<Big Brother update> process will print out
+I<spong update> and I<Big Brother update> process will print out
host/service/color of every status message that is received.
The update processes will print out their actions concerning notifications. If
-a notification is indicated, <spong-server> will call B<spong-message> with the
+a notification is indicated, B<spong-server> will call B<spong-message> with the
B<--debug> parameter if B<--debug> was specified in the command line.
=item B<spong-client>
a number which is the date/time in epoch format (i.e.
the number of seconds since 00:00 01/01/1970). Just pick a big number.
-=back
+=back
+
+=back
B<spong-message> will print out the current rule number (starting with 0).
The the success or failure of all of the checks of the matching
program) and named "header.html" or "footer.html", respectively.
Place the HTML code that you want display into the template files.
-You can also specifiy other HTML files to be included when the file is
+You can also specify other HTML files to be included when the file is
display. Insert the string "B<!!WWWSHOW!!>/filename" into
the place that your desire the file named "filename" to be display. The
file to be include should placed into the same directory are the "header.html"
or "footer.html" file resides.
B<Note:> This customization feature is limited in the current release.
-More substiution variables (i.e. hostname, service, status, etc)
+More substitution variables (i.e. hostname, service, status, etc)
will be added into future. As will the ability to select which type of
pages the headers or footer will be placed (i.e. service status screen,
server display screen, history screen, problem screen, etc.)
The .txt files are used with text mode displays like those generated by the
B<spong> display command (see L<spong>). The .html files are used by the html
-mode displays. The .html files can contain html code, URLs, embeded graphics,
+mode displays. The .html files can contain html code, URLs, embedded graphics,
Javascript, or anything that you display on a web page.
link on a page's action bar that has the hostname and a message which contains
all of the current problems that system currently has.
-The "Contact Staff" link's URL consists of two parts. The first part is the
+The "Contact Staff" link URL consists of two parts. The first part is the
I<$WWWCONTACT> from the F<spong.conf> configuration file (see
L<spong.conf/"$WWWCONTACT">). It contains the URL to your contact
staff CGI program that you must supply (see below). The second part of the are
=head2 Customized Action Bar
-The Action Bar of the Host and Service Status Displays (see the L<User
-Guide|user-guide> for more details) can be customized with the
-I<$WWW_ACTIONBAR_CUSTOM> configuration parameter (see
-L<spong.conf/"$WWW_ACTIONBAR_CUSTOM">). Any HTML code
-defined in this parameter will be included at the end of the Action Bars.
+The Action Bar of the Host and Service Status Displays (see L<user-guide>
+for more details) can be customized with the I<$WWW_ACTIONBAR_CUSTOM>
+configuration parameter (see L<spong.conf/"$WWW_ACTIONBAR_CUSTOM">). Any HTML
+code defined in this parameter will be included at the end of the Action Bars.
This parameter is preprocessed with the Perl C<eval> function before the
contents are printed. This allows you to include complex perl variables or perl
If your do not need this customization, just leave B<$WWW_ACTIONBAR_CUSTOM>
undefined. Nothing will be added to the Action Bars.
-=head2 B<$WWW_REFRESH> Logic
+=head2 $WWW_REFRESH Logic
The default of the spong-server is to not allow auto-refreshes if
B<@WWW_REFRESH_ALLOW> and B<@WWW_REFRESH_DENY> variables are empty (see
queries the spong-server web pages, the auto-refresh would be allowed because
it matches the '^192.168.12.*' expression of I<@WWW_REFRESH_ALLOW>. But if the
user was 'fred' at the same machine (192.168.12.143), auto-refresh would not be
-enabled because 'fred' is in the I@<WWW_RERESH_DENY> list.
+enabled because 'fred' is in the I@<WWW_REFRESH_DENY> list.
=head1 SEE ALSO
=head1 DESCRIPTION
This is the developer guild to Spong. It documents the inner workings of the
-client and server programs. It also describes the plugin mechanism of the
+client and server programs. It also describes the plug-in mechanism of the
B<spong-client> and B<spong-network> so that new check modules can be
developed for these programs.
=head1 PROTOCOLS
-This section deals with the low level communucation protocols that the clients
+This section deals with the low level communication protocols that the clients
use to talk with the B<spong-server>. The Spong and Big Brothers protocols
almost identical. They vary only in the data format.
After a socket has been opened, the client program sends a message with the
following format:
- command host service color time[:ttl] summary (\n)
+ command host service color time[:TTL] summary (\n)
detailed status message line 1 (\n)
detailed status message line 2 (\n)
...
Where:
-=over
+=over 4
=item command
The date/time of the update message in epoch time format
(i.e. the number of seconds since 01/01/70, 00:00 AM)
-=item ttl
+=item TTL
This optional field is the time to live, in seconds, for the status message.
Normally a will become stale (i.e. purple status) after 2 times $SPONGSLEEP
-seconds which is the default. See L<spong.conf/"$SPONGSLEEP". This field will
-override the defaiult and keep the status message valid for a longer period of
+seconds which is the default. See L<spong.conf/"$SPONGSLEEP">. This field will
+override the default and keep the status message valid for a longer period of
time.
=item summary
The status summary message field. A short and to the point message that
-summarises the status being returned.
+summarizes the status being returned.
=item detailed status message
The remained lines of the message which will be the detailed information of the
-status. Typically it can be the output of the df command or the top processes
-by CPU utilization or the detailed reponses of network checks.
+status. Typically it can be the output of the C<df> command or the top processes
+by CPU utilization or the detailed responses of network checks.
=back
Where:
-=over
+=over 4
=item command
The remained lines of the message
which will be the detailed information of the status. Typically it can
be the output of the df command or the top processes by CPU utilization
-or the detailed reponses of network checks.
+or the detailed responses of network checks.
=back
B<spong-client>, B<spong-network>, B<spong-message> and B<spong-server> use
various routines which are coded as modules. When the programs are
-initializating, they determine which modules are going to be required. The
+initializing, they determine which modules are going to be required. The
programs then go out and load each of the modules from the library directory.
-When the modules are loaded they register themselves with the plugins
-registery. The plugin registry is the mechanism that the client programs use
+When the modules are loaded they register themselves with the plug-ins
+registry. The plug-in registry is the mechanism that the client programs use
to keep track of the modules into order to run them.
=head2 SERVER MODULES
The module should not call the E<amp>main::status() function directly.
B<spong-network> has a mechanism for rechecking services that are reported down
-on an initial check. If the recheck mechanism is engauged, "red" statuses will
+on an initial check. If the recheck mechanism is engaged, "red" statuses will
be downgraded to "yellow" until a failure count threshold is reached. The the
services will be reported as "red".
After the status condition has been determined the check function should return
-three parameterers:
+three parameters:
-=over
+=over 4
=item STATUS
These parameters are the same that will be passed to the C<E<amp>main::status()>
command. See L<"Status Function"> for more information on these parameters.
-The network modules have two support functions avaiable,
+The network modules have two support functions available,
C<E<amp>main::check_tcp()> and C<E<amp>main::check_simple()>, which can
simplify simple TCP port checks.
Where the arguments are:
-=over
+=over 4
=item HOST
Where the arguments are
-=over
+=over 4
=item HOST
=item SEND
-The messge to sent to the host after the port is opened.
+The message to sent to the host after the port is opened.
=item CHECK
=item SERVICE
-The name of the sevive being check. It is used in the summary
+The name of the service being check. It is used in the summary
and detailed status messages.
The function C<E<amp>main::check_simple()> is a generic TCP port checking
The messaging functions has access to these global variable in order format
a notification message:
-=over
+=over 4
=item I<$color>
=item I<$message>
-A one line summary status line</li>
+A one line summary status line
=item I<$duration>
Where the arguments to the functions are:
-=over
+=over 4
=item RECIPIENT
Creating the actual modules is very trivia to do. Create your module by
following the appropriate template from below.
-=over
+=over 4
-=item o
+=item *
-L<spong-client module template|spong-client-mod-template>
+L<spong-client Module Template|spong-client-mod-template>
-=item o
+=item *
-L<spong-network module template|spong-network-mod-template>
+L<spong-network Module Template|spong-network-mod-template>
-=item o
+=item *
-L<spong-message module template|spong-message-mod-template>
+L<spong-message Module Template|spong-message-mod-template>
-=item o
+=item *
-L<spong-server data module template|spong-server-mod-template>
+L<spong-server Module Template|spong-server-mod-template>
=back
-Then place your template module file into the appropirate directory below.
+Then place your template module file into the appropriate directory below.
-=over
+=over 4
-=item
+=item *
B<spong-client> - F<LIBDIR/Spong/Client/plugins>
-=item
+=item *
-B<spong-nework> - F<LIBDIR/Spong/Network/plugins>
+B<spong-network> - F<LIBDIR/Spong/Network/plugins>
-=item
+=item *
B<spong-message> - F<LIBDIR/Spong/Message/plugins>
-=item
+=item *
B<spong-server> - F<LIBDIR/Spong/plugins>
The arguments to the C<E<amp>main::status()> function are:
-=over 8
+=over 4
=item SERVERADDR
normal parameters. "yellow" denotes a warning status, a abnormal situation that
has which may be need to be looked at or a parameter has changed (up or down)
towards a critical level. "red" denotes an alert status, a critical situation
-that has arised and needs immediate attenation or a parameter has changed (up
+that has arisen and needs immediate attention or a parameter has changed (up
or down) to a critical level.
=item SUMMARY
=item MESSAGE
This is the place to put detailed information about the status of the service.
-Typically this will be the output of the system commands or function calls. For example, it could be the 10 jobs by cpu usage in a ps command, or the output
+Typically this will be the output of the system commands or function calls. For example, it could be the 10 jobs by cpu usage in a C<ps> command, or the output
of a df command for disk checking.
There are no limitations on the contexts of the field. You can include URL's
=head1 SEE ALSO
-L<spong-server>, L<spong-client>, L<spong-network>, L<spong-messsage>,
+L<spong-server>, L<spong-client>, L<spong-network>, L<spong-message>,
L<spong-server-mod-template>, L<spong-client-mod-template>,
L<spong-network-mod-template>, L<spong-message-mod-template>, L<spong.conf>
--- /dev/null
+=head1 NAME
+
+B<spong-ack> - Spong acknowledgment tool
+
+=head1 SYNOPSIS
+
+B<spong-ack> [B<--debug>] [B<--batch>] host services time [message]
+
+B<spong-ack> [B<--debug>] B<--delete> ack-id
+
+=head1 DESCRIPTION
+
+When a spong event occurs (or will occur), you can use this tool to acknowledge
+that you know that there is a problem. You can provide text that will be seen
+by others looking at the event (via a spong display program). You can specify
+at time limit that the problem will occur. If a problem has been acknowledged,
+you will no longer received notifications of the problem, and the display
+programs will show the status of the service as "blue".
+
+=head1 OPTIONS
+
+=over
+
+=item B<--debug>
+
+Print debugging statements. This option can be specified while creating or deleting acks.
+
+=item B<--batch>
+
+Print the ack-id instead of the normal output. The primary use of this parameter
+is for scripts. An ack can be created when a job that runs causes a service to
+temporarily exceed it's normally limits, or if a service is taken down for an
+unknown or irregular length of time.
+
+=item B<--delete>
+
+Delete a previously created ack.
+
+=back
+
+Here is a description of the arguments for creating acks:
+
+=over
+
+=item host
+
+The host having the problem(s) you are acknowledging.
+
+=item service
+
+The service or services (separated by ".") or I<all> services that your are
+acknowledging.
+
+=item time
+
+The that the acknowledgement will late. This can be an offset "+1h, +3a,d +1w" or
+an absolute date and/or time indicator "12/25/1997 14:00:00. The date needs to be
+a 4 digit year, and the time needs to be in 24 hour format.
+
+=item message
+
+An optional message that will appear to those viewing the state of the host with a
+spong display program. If the value is "-", then the message will read from STDIN.
+
+=back
+
+Here is a description of the arguments for deleting acks:
+
+=over
+
+=item ack-id
+
+The acknowledgment id to delete. The id can be obtained by using the B<--batch>
+parameter when creating the acknowledgment, or by using the L<spong> command
+with the B<--brief> and B<--ack> parameters.
+
+=back
+
+=head1 CONFIGURATION
+
+=head2 Configuration Files
+
+B<spong-cleanup> reads the standard spong.conf and spong.conf.E<lt>hostE<gt>
+configuration files.
+
+=head2 Configuration Variables
+
+=over
+
+=item $SPONGSERVER
+
+The host that at least the L<spong-server> and L<spong-message>
+programs are running on. Typically the L<spong-network> program runs on that
+host as well.
+
+=item $SPONG_UPDATE_PORT
+
+This variable defines the port that the L<spong-server> update process listens
+on. If this variable is not defined on the I<$SPONGSERVER> host, the
+L<spong-server> update process will not be started. The default value is 1998.
+
+=back
+
+=head1 FILES
+
+F<SPONGHOME/etc/spong.conf>, F<SPONGHOME/etc/spong.conf.E<lt>hostE<gt>>
+
+=head1 EXAMPLES
+
+ spong-ack mailhub.my-inc.com all '05/27/2000 06:00:00' 'Server is being upgraded'
+
+ spong-ack www5.my-inc.com http +1h 'Web server is randomly dying. Investigating.'
+
+In a shell script:
+
+ ...
+ HOST=`hostname`
+ ACKID=`spong-ack --batch $HOST cpu +8h 'Database exports are running'`
+ ...
+ # Database exports are done here
+ ...
+ spong-ack --delete $ACKID
+ ...
+
+=head1 DEPENDENCIES
+
+Perl v5.005_03 or greater is required.
+
+=head1 BUGS
+
+No know bugs.
+
+=head1 SEE ALSO
+
+L<spong-server>, L<spong.conf>, L<developer-guide>
+
+=head1 AUTHOR
+
+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 development until
+version 2.1. Stephen L Johnson took over development in October, 1999 with his
+changes which became Spong 2.5.
+
+
-=head1 NAME\r
-\r
-spong-client-mod-template - how to create modules for spong-client\r
-\r
-=head1 DESCRIPTION\r
-\r
-This document describes how to create your own plugin modules for\r
-the B<spong-client> program. Your modules can be your own new custom check or\r
-they can replacements for the core Spong modules.\r
-\r
-This template assumes that you are creating a new client check\r
-called 'mailq'. The name of the file created should be 'check_mailq'. The\r
-file name for B<spong-client> modules should always be 'check_' plus the\r
-registry name (e.g. for the foo check, the registry name is 'foo' and the file\r
-name is 'check_foo').\r
-\r
-The line that has the assignment to I<$CHECKFUNC{'registry-name'}> is the\r
-key to the registry mechanism. It's what ties the registry name to the\r
-actual checking function.\r
-\r
-The registry name does not always have to match up to the service name as in\r
-this case of out module 'mailq'. If you where creating a new and improved\r
-function to check mail queues, you could create a module called 'my_mailq'. You\r
-would use the registry name 'my_mailq', but you would use the service name\r
-'mailq' in the C<E<amp>status()> function when reporting your info back to\r
-the server.\r
-\r
-check_mailq:\r
-\r
- # Register my routine with plugin registry\r
- $CHECKFUNCS{'mailq'} = &check_mailq;\r
-\r
- # Sendmail mail queue check for mail servers. It checks the number of mail\r
- # message queued against the $MAILQWARN AND $MAILQCRIT variables.\r
- # It runs the command in the config variable $MAILQ to do it's check.\r
-\r
- sub check_mailq {\r
- my($mqcnt, $message, $color, $summary );\r
-\r
- open (FOO,"$MAILQ |");\r
-\r
- $mqcnt = 0;\r
- while (<FOO>) {\r
- if (/Mail Queue\s+\((\d+)/) { $mqcnt = $1; }\r
-\r
- # Grab enough to get the first 10 entries.\r
- if (++$lines <= 35) { $message .= $_ };\r
- }\r
- close FOO;\r
-\r
- $color = "green";\r
-\r
- if ($mqcnt > $MAILQWARN) { $color = "yellow"; }\r
- if ($mqcnt > $MAILQCRIT) { $color = "red"; }\r
- $summary = "Mail Queue count = $mqcnt"\r
-\r
- &main::debug("mailq - $color, $summary")\r
- &main::status( $SPONGSERVER, $HOST, "mailq", $color,\r
- $summary, $message );\r
-\r
- }\r
-\r
- # I'm include perl code, I need this line.\r
- 1;\r
-\r
-Please note the final line. It is always required for a module file.\r
-\r
-The I<$MAILQWARN> and I<$MAILQCRIT> variables are added to the F<spong.conf>\r
-or F<spong.conf.E<lt>hostnameE<gt>> configuration files. These variable define\r
-the warning and alert threshold levels for your custom check.\r
-\r
-Configuration variable for your custom checks should be named to match them up\r
-with the name of your customized check. In our case, we started our variable\r
-names with MAILQ with matches up nicely with our module name of 'mailq'. Naming\r
-the threshold variables $WARN_SPOOL_LEVEL and $CRIT_SPOOL_LEVEL would have made it unclear as to which check they belonged to. Keep the names similar, it will\r
-make it easier on you and others to administer your setup in the future.\r
-\r
-=head1 SEE ALSO\r
-\r
-L<developer-guide>, L<spong-client>, L<spong.conf>\r
-\r
-=head1 AUTHOR\r
-\r
-Stephen L Johnson <F<sjohnson@monsters.org>>\r
-\r
-=head1 HISTORY\r
-\r
-Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong). Ed Hill\r
-original converted Big Brother (http://www.bb4.com) into Perl which diverged\r
-from Big Brother to become Spong. Ed Hill continued Spong development until\r
-version 2.1. Stephen L Johnson took over development in October, 1999 with his\r
-changes which became Spong 2.5.\r
-\r
+=head1 NAME
+
+spong-client-mod-template - how to create modules for spong-client
+
+=head1 DESCRIPTION
+
+This document describes how to create your own plug-in modules for
+the B<spong-client> program. Your modules can be your own new custom check or
+they can replacements for the core Spong modules.
+
+This template assumes that you are creating a new client check
+called 'mailq'. The name of the file created should be 'check_mailq'. The
+file name for B<spong-client> modules should always be 'check_' plus the
+registry name (e.g. for the foo check, the registry name is 'foo' and the file
+name is 'check_foo').
+
+The line that has the assignment to I<$CHECKFUNC{'registry-name'}> is the
+key to the registry mechanism. It's what ties the registry name to the
+actual checking function.
+
+The registry name does not always have to match up to the service name as in
+this case of out module 'mailq'. If you where creating a new and improved
+function to check mail queues, you could create a module called 'my_mailq'. You
+would use the registry name 'my_mailq', but you would use the service name
+'mailq' in the C<E<amp>status()> function when reporting your info back to
+the server.
+
+check_mailq:
+
+ # Register my routine with plug-in registry
+ $CHECKFUNCS{'mailq'} = &check_mailq;
+
+ # Sendmail mail queue check for mail servers. It checks the number of mail
+ # message queued against the $MAILQWARN AND $MAILQCRIT variables.
+ # It runs the command in the config variable $MAILQ to do it's check.
+
+ sub check_mailq {
+ my($mqcnt, $message, $color, $summary );
+
+ open (FOO,"$MAILQ |");
+
+ $mqcnt = 0;
+ while (<FOO>) {
+ if (/Mail Queue\s+\((\d+)/) { $mqcnt = $1; }
+
+ # Grab enough to get the first 10 entries.
+ if (++$lines <= 35) { $message .= $_ };
+ }
+ close FOO;
+
+ $color = "green";
+
+ if ($mqcnt > $MAILQWARN) { $color = "yellow"; }
+ if ($mqcnt > $MAILQCRIT) { $color = "red"; }
+ $summary = "Mail Queue count = $mqcnt"
+
+ &main::debug("mailq - $color, $summary")
+ &main::status( $SPONGSERVER, $HOST, "mailq", $color,
+ $summary, $message );
+
+ }
+
+ # I'm include perl code, I need this line.
+ 1;
+
+Please note the final line. It is always required for a module file.
+
+The I<$MAILQWARN> and I<$MAILQCRIT> variables are added to the F<spong.conf>
+or F<spong.conf.E<lt>hostnameE<gt>> configuration files. These variable define
+the warning and alert threshold levels for your custom check.
+
+Configuration variable for your custom checks should be named to match them up
+with the name of your customized check. In our case, we started our variable
+names with MAILQ with matches up nicely with our module name of 'mailq'. Naming
+the threshold variables $WARN_SPOOL_LEVEL and $CRIT_SPOOL_LEVEL would have made it unclear as to which check they belonged to. Keep the names similar, it will
+make it easier on you and others to administer your setup in the future.
+
+=head1 SEE ALSO
+
+L<developer-guide>, L<spong-client>, L<spong.conf>
+
+=head1 AUTHOR
+
+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 development until
+version 2.1. Stephen L Johnson took over development in October, 1999 with his
+changes which became Spong 2.5.
+
--- /dev/null
+=head1 NAME
+
+spong-client - report system information to spong server
+
+=head1 SYNOPSIS
+
+B<spong-client> [ B<--debug>|B<-d> I<n> ]
+[ B<--kill>|B<--restart>|B<--nosleep>|B<--norefresh> ] F<config-file>
+
+=head1 DESCRIPTION
+
+This program is run on each Unix machine in which you want
+to monitor local system attributes, and report that information to the
+spong server. It runs one or more configured checks. It then sleeps for
+a time period you have defined in your configuration file and does it all
+again (it actually adds or subtracts a random amount of time - no more
+then 10% of the total you have specified, to keep clients from sync'ing
+up and overloading the spong-server).
+
+The checks are modular in nature. You can configure the number of checks
+to run and the order in which to run to them. The list of checks that are
+included are disk space, cpu load, running processes and log files.
+
+=head2 Format of update messages
+
+It sends a message for each check to the spong server and reports the
+following:
+
+=over 4
+
+=item * hostname (where is this report coming from)
+
+=item * service name ("disk", "cpu", "procs", "logs", "local")
+
+=item * color ("red", "yellow", "green")
+
+=item * a one line summary
+
+=item * a more detailed message providing additional detail.
+
+=back
+
+
+The color is determined by comparing the current status of that service
+against thresholds defined in the configuration file. If they are greater
+then the level you have defined for a warning, then the color is yellow.
+If they are greater then the critical level you have defined then the color
+is red.
+
+The one line summary provides information that might be useful at a
+glance when looking at the overall system status (such as a brief report
+on the load, number of users, and uptime).
+
+The more detailed message contains information such as the complete
+C<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 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
+configuration files. If you provide the B<--kill> flag, a signal will be sent
+to the running spong-client process causing it to exit.
+
+The B<--nosleep> or B<--refresh> flag causes the program to cycle through all
+of the checks once then exit. These flags can be used to run spong-client as a
+cron job (B<depreciated>), this reduced the effectiveness of the B<check_logs>
+module.
+
+=head2 Client Checks
+
+The checks are actually a set of modules that are called in series by
+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 registry (see the L<Developer Guide|developer-guide>).
+
+=head2 Extending Functionality
+
+B<Depreciated>, please refer to L<developer-guide/"CLIENT MODULES">.
+
+If you want to check some service which is not being checked by spong-client,
+then you can define a C<&check_local()> function in your
+config file (either in your standard L<spong.conf> config file or your host specific L<spong.conf.hostname|spong.conf>
+file - but not both!). That function can do anything you want, but at the
+end needs to call the C<&status()> function to report
+what you have found to the spong server.
+
+=head1 CONFIGURATION
+
+=head2 Configuration Files
+
+By default this reads the L<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
+hostname of the machine that you are running on. Since these configuration
+files are just standard perl code that gets imported, the variables that you
+define in the host specific config file will take precedence over the standard
+configuration settings.
+
+=head2 Configuration Variables
+
+Here is a listing of the configuration variables applicable to the
+B<spong-client> program.
+
+=over
+
+=item $SPONGSLEEP, $SPONGSERVER, $SPONG_UPDATE_PORT
+
+Some basic spong configuration options that define how long to sleep (in
+seconds) before checking the status of a service again, the hostname of the
+spong server, and the port number that the spong server listens
+
+=item $SPONGSLEEP{'DEFAULT'}, $SPONGSLEEP{'spong-client'}
+
+This the new method for specifying the $SPONGSLEEP interval for Spong programs.
+If there is not $SPONGSLEEP{} entry for the program, it will use the
+I<$SPONGSLEEP{'DEFAULT'}> value. If no value is then found, B<spong-client>
+fall back to using $SPONGSLEEP.
+
+=item $SPONGTMP
+
+The directory that Spong programs use for temporary store and work files. It
+should be different directory than F</tmp> for operation and security reasons.
+
+=item $SPONG_LOG_FILE
+
+If set to I<1>, B<spong-client> will log errors to a log file in I<$SPONGTMP>
+named F<spong-client.log>.
+
+=item $SPONG_LOG_SYSLOG
+
+If set to I<1>, B<spong-client> will log errors to the syslog using the
+I<USER> facility and the B<ERR> priority.
+
+=item $CHECKS
+
+A string that has the list of client check modules to run. If I<$CHECKS> is
+missed or blank, spong-client defaults to "disk cpu processes logs". If the
+C<check_local()> function is present then 'local' is appended.
+
+=item $CPUWARN, $CPUCRIT
+
+A number indicating the CPU load that triggers a problem (I<$CPUWARN>
+triggers warnings - yellow, and I<$CPUCRIT> triggers alerts - red).
+
+=item @PROCSWARN, @PROCSCRIT
+
+A list of processes that should be running, if they are not running, then
+trigger a problem (processes in I<@PROCSWARN> trigger a warning - yellow, and
+processes in I<@PROCSCRIT> trigger an alert - red).
+
+=item $LOGCHECKS
+
+A list of hashes which defined checks to apply to log files. Each hash
+contains the fields:
+
+=over
+
+=item logfile
+
+which is the full path to the log file to check
+
+=item checks
+
+a list of check to apply to the log file.
+
+=back
+
+Each check is a hash that contains the fields:
+
+=over
+
+=item pattern
+
+a Perl regular expression to be scanned for
+
+=item status
+
+the status color to reported lines matching pattern
+
+=item duration
+
+the duration (in seconds) that each event is to be reported to the server
+
+=item text
+
+a string which is the the text to be reported
+back in the detailed message field of the status report (which can include
+match position variables from I<pattern>)
+
+=item id
+
+an optional key field to associated with each event generated. The default
+key is the evaluated I<text> field. An id key may be specified for the
+for a check pattern. All hits of the pattern will be consolidated into one
+event. The data of the last hit will be reported in the event.
+
+=back
+
+=item $DF, $UPTIME, $PS, $GREP
+
+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.
+
+=back
+
+
+=head1 FILES
+
+F<spong.conf>, F<spong.conf.[hostname]>
+
+=head1 EXAMPLES
+
+ spong-client --debug 5 --nosleep
+ spong-client --debug 5
+ spong-client --restart
+
+=head1 DEPENDENCIES
+
+Perl v5.005_03 or greater is required.
+
+=head1 BUGS
+
+None know bugs.
+
+=head1 SEE ALSO
+
+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
+
+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 development until
+version 2.1. Stephen L Johnson took over development in October, 1999 with his
+changes which became Spong 2.5.
=item *
-easily expandable via a plugin module facility
+easily expandable via a plug-in module facility
=back
trying to turn it into one. It is not SNMP based, it communicates via simple
TCP based messages. It is written in Perl, so hopefully it can be run on
multiple systems (including NT - although it has not been ported yet -
-but is on the todo list).
+but is on the to-do list).
I'm a strong believer in KISS (keep it simple stupid), and hopefully
this package is as simple as possible (but no simpler). Spong is broken
=over
-=item B<spong>
+=item *
+
+L<spong|spong>
Text based query program, reports information about hosts that are
monitored.
-=item B<www-spong>
+=item *
+
+L<www-spong|www-spong>
Web based query program, reports information about host that are monitored.
-=item B<spong-client>
+=item *
+
+L<spong-client|spong-client>
Program that runs on each monitored server. Reports host based information
(disk, cpu, logs, etc.)
-=item B<spong-network>
+=item *
+
+L<spong-network|spong-network>
Reports on network based services (smtp, ping, http, etc.)
-=item B<spong-server>
+=item *
+
+L<spong-server|spong-server>
Collects information reported and responds to queries about that information.
-=item B<spong-message>
+=item *
+
+L<spong-message|spong-message>
Called by the B<spong-server> program to send out notifications when
problems occur.
=head1 SUPPORT
-There are two mailings setup for Spong: spong-users and spong-annouce.
+There are two mailings setup for Spong: spong-users and spong-announce.
spong-users is for general discussions or getting help for Spong. You can
-ubscribe by sending a message to spong-users-request@lists.sourceforge.net
+subscribe by sending a message to spong-users-request@lists.sourceforge.net
with the work subscribe in the message. Or be visiting the mailing lists
-home page at F<http://lists.sourceforce.net/mailman/listinfo/spong-users>.
+home page at F<http://lists.sourceforge.net/mailman/listinfo/spong-users>.
-spong-annouce
-is a low-volume mailing which will be used for annoucements and news concerning
-Spong. It is moderated, but feel free to submit any pertinet items. You can
-ubscribe by sending a message to spong-annouce-request@lists.sourceforge.net
+spong-announce
+is a low-volume mailing which will be used for announcements and news concerning
+Spong. It is moderated, but feel free to submit any pertinent items. You can
+subscribe by sending a message to spong-announce-request@lists.sourceforge.net
with the work subscribe in the message. Or be visiting the mailing lists
-home page at F<http://lists.sourceforce.net/mailman/listinfo/spong-annouce>.
+home page at F<http://lists.sourceforge.net/mailman/listinfo/spong-announce>.
=head1 DEPENDENCES
The documentation is provided in perl POD format (the old Perl pod
format just didn't do all that I wanted). The installation process will create
-HTML, text and man fomatted versions of the documentation. The HTML
-documentation can be located anywhere. It's crosslinks should survive a move
+HTML, text and man formatted versions of the documentation. The HTML
+documentation can be located anywhere. It's cross-links should survive a move
intact.
There are four main documents that describe spong from different
=over
-=item L<FAQ|spongfaq.pod>
+=item *
+
+L<FAQ|spongfaq>
Frequently Asked Questions by users and their answers.
-=item L<User's Guide|user-guide>
+=item *
+
+L<User-Guide|user-guide>
Geared towards the person who will be using the spong text or web based
clients. This is the documentation that will be seen when the user clicks
on the Help button provided in www-spong.
-=item L<Administrator's Guide|admin-guide>
+=item *
+
+L<Administrator's Guide|admin-guide>
Written for the person who will be installing spong, and setting up the
various configuration files. This provides a step by step installation
process and gives some suggestions on things B<Spong> can do that you might
not have thought of.
-=item L<Developer's Guide|developer-guide>
+=item *
+
+L<Developer's Guide|developer-guide>
Written for the person who wants to have B<Spong> look differently, or what
-to add some new feature in their version of spong, or whats to incorporate
+to add some new feature in their version of spong, or wants to incorporate
spong output in other programs. This details the B<Spong> internals, and
describes the various protocols that are used.
www-spong.pl web based spong display client
-www-spong-ack.pl web based acknowledgement program</pre>
+www-spong-ack.pl web based acknowledgement program
docs:
=head1 CHANGES
The list of changes for the latest version of B<Spong> can be found
-at L<http://spong.sourceforge.net/documentation/CHANGES>
+at I<http://spong.sourceforge.net/documentation/CHANGES>.
=over
=item Version 2.5
-First releae by Stephen L Johnson. Rules based notifications added,
+First release by Stephen L Johnson. Rules based notifications added,
a limited Big Brother Server emulation was to allow Big Bother Clients
-to be used. A new log monitoring routnie which tracks last position read.
+to be used. A new log monitoring routine which tracks last position read.
Enhanced network checks to eliminate momentary network problems.
=item Version 2.0
and comments, and where willing to try out spong and help me work out a
few of the early problems.
-=head2 by Stephen L johnson
+=head2 by Stephen L Johnson
I first found Big Brother and liked what it did. But I was put as a bit by
-it being written in C and shell scripts. While purusing the Big Brother mailing
+it being written in C and shell scripts. While perusing the Big Brother mailing
lists archives I ran across references to Spong, and it being written in Perl.
This was Spong 1.1
-I tried it out but there were some stablity problems. So I reluctantly dropped
+I tried it out but there were some stability problems. So I reluctantly dropped
Spong in favor of Big Brother. I didn't like some of the limitations of
Big Brother, so I started hacking on the source code. To me it was akin to
writing in assembler and getting a tooth pulled. I don't like either one.
if I could have Spong 2.1. He sent me the distribution and I started evaluating
it again.
-Spong 2.1 was a big improvement over Spong 1.1 in terms of stablility
+Spong 2.1 was a big improvement over Spong 1.1 in terms of stability
and features. I rolled the changes that I made to Big Brother into Spong 2.1
and I have been changing things ever since.
The program memory core size grows after each check cycle. The fix is to
upgrade the glibc from version 2.1.1 to version 2.1.2.
+=back
+
=head1 AUTHOR
Ported by:
--- /dev/null
+#!@@PERL@@
+
+=head1 NAME
+
+B<spong-message> - send out alerts when there is a problem
+
+=head1 SYNOPSIS
+
+B<spong-message> [B<--debug>] [B<--file> I<filename> | B<--message> I<"detailed
+message text">] I<color> I<host> I<service> I<time> I<message>
+
+B<spong-message> [B<--debug>] B<--color|--status> I<color> B<--host>
+I<hostname> B<--service> I<service> B<--time> I<time> B<--summary> I<"summary
+message text"> [B<--file> I<filename> | B<--message> I<"detailed message
+text">]
+
+=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.message> 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.
+
+=head2 Options
+
+=over
+
+=item B<--debug>
+
+Enables the printing of detailed debugging lines. Can be used in conjunction
+with B<--test> to test new messaging rules.
+
+=item B<--color|--status> I<color>
+
+Specified the status color of the event being reported. I<color> can be
+green, yellow or red.
+
+=item B<--host> I<hostname>
+
+The hostname of the server that is being reported on.
+
+=item B<--service> I<service>
+
+The name of the service that is being reported on.
+
+=item B<--time> I<time>
+
+The time of the event being reported in epoch format (i.e. time()).
+
+=item B<--summary> I<"summary text">
+
+This is the summary message field of the event being reported on.
+
+=item B<--file> I<filename>
+
+The name of a file to read the detailed message text from. If the I<filename> is S<'-'>, the text is read from stdin.
+
+=item B<--message> I<"message text">
+
+Detailed message text of the event being reported.
+
+=back
+
+The following parameters can be specified on the command line with the
+accompanying command line parameters.
+
+=over
+
+=item color
+
+the status color of the message (B<red>, B<yellow>, or B<green>)
+
+=item host
+
+the hostname being of the alert
+
+=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 maintenance 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<acknowledgements|spong-ack> 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 Message Templates
+
+Notification messages are formatted by message templates in the %TEMPLATES
+configuration variable in the F<spong.message> file. The 'DEFAULT' template
+is use is no other template is found. Templates override can be defined for any
+contact, message module, or a combination of the two. See
+L<spong.message/"MESSAGE TEMPLATES"> for information on the file format.
+
+=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>.
+
+=head1 CONFIGURATION
+
+=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">), 2) the messaging rules
+(L<$MESSAGING_RULES|spong.message/"$MESSAGING_RULES">), 3) how to format the
+messages being sent (L<%TEMPLATES|spong.message>).
+
+=back
+
+=head2 Configuration Variables
+
+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.
+
+=item %TEMPLATES
+
+C<%TEMPLATES> determined how notification message are formatted. A template
+format consists a subject and message template strings. Both strings are not
+required as some message module will not require a subject or a body. See
+L<$MESSAGING_RULES|spong.message/"$MESSAGING_RULES"> for the full rules syntax.
+
+=back
+
+From F<spong.conf>:
+
+=over 4
+
+=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 every time 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
+
+F<spong.conf>,
+F<spong.hosts>,
+F<$SPONGTMP/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, }, ]
+ },
+
+ ];
+
+ %TEMPLATES = (
+
+ 'DEFAULT' => { subject => 'spong - !!COLOR!! !!HOST!! !!SERVICE!!',
+ body =>
+ '!!DATETIME!!
+ !!COLOR!! !!HOST!! !!SERVICE!!
+ !!SUMMARY!!',
+ },
+
+ 'email' => { subject => 'spong - !!COLOR!! !!HOST!! !!SERVICE!!',
+ body =>
+ 'Host !!HOST!! service has been reported !!COLOR!!.
+ Summary: !!SUMMARY!!
+
+ Spong Web Page: !!WWWSPONG!!
+ Service Detail Page: !!WWWSPONG!!/service/!!HOST!!/!!SERVICE!!
+
+ Status event details:
+ !!DETAILED!!
+ ',
+ },
+ );
+
+=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<spong-message-mod-template>, L<strftime(3)>
+
+=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 development until
+version 2.1. Stephen L Johnson took over development in October, 1999 with his
+changes which became Spong 2.5.
-=head1 NAME\r
-\r
-spong-nework-mod-template - A sample spong-network check module\r
-\r
-=head1 DESCRIPTION\r
-\r
-This document describes a sample plugin module for the B<spong-network>\r
-program. Any modules that you create can be custom network checks, or they\r
-can be replacements for the core Spong modules.\r
-\r
-This template assumes that you are creating a network check called\r
-'dns'. The name of the file created should be 'check_dns'. The file name\r
-should always be 'check_' plus the registry name (e.g. for the foo check,\r
-the registry name is 'foo' and the file name is 'check_foo'.\r
-\r
-The line that has the assignment to $PLUGINS{'registry-name'} is the\r
-key to the registry mechanism. It's what ties the registry name to the\r
-the checking function.\r
-\r
-The registry name does not always have to match up to the service name as in\r
-the case of our module 'dns'. If you where creating a new and improved function\r
-to ping and traceroute, you could create a module called 'ping_trace'. You\r
-would use the registry name 'ping_trace', but you would use the service name\r
-'ping' in the C<E<amp>main::status()> function when reporting your information\r
-back to the server.\r
-\r
-check_dns:\r
-\r
- # Register the routine with the plugin registry\r
- $PLUGINS{'dns'} = \&check_dns;\r
-\r
- # Check to see if they have the Net::DNS module installed, and if they do we\r
- # can then do DNS queries, and see if DNS servers are alive.\r
-\r
- eval "require Net::DNS;";\r
- if( ! $@ ) { $dns = 1; } else { $dns = 0; }\r
-\r
- # This check will (if the Net::DNS module is available) connect to a DNS\r
- # server and ask that server to resolve it's own name. If it can do that,\r
- # then we assume it is ok - If it can't then something is wrong.\r
-\r
- sub check_dns {\r
- my( $host ) = @_;\r
- my( $color, $summary, $message ) = ( "green", "", "" );\r
-\r
- if( ! $dns ) {\r
- $summary = "can't do DNS lookups, Net::DNS not installed";\r
- &main::debug( "dns - $host - $color, $summary" );\r
- return ( "yellow", $summary,\r
- "In order to do DNS queries you must install the Net::DNS " .\r
- "Perl module.\nYou can find the module at your nearest CPAN " .\r
- "archive or http://www.perl.com/CPAN/\n" )\r
- }\r
-\r
- my $resolver = new Net::DNS::Resolver;</tt>\r
- $resolver->nameservers( $host );\r
- $resolver->retrans(2);\r
- $resolver->retry(1);\r
- $resolver->recurse(0);\r
- my $q = $resolver->search( $host, "A" );</tt>\r
-\r
- if( defined $q && defined $q->answer && defined (($q->answer)[0]) ) {\r
- $color = "green";\r
- $summary = "dns ok";\r
- } else {\r
- $color = "red";\r
- $summary = "can't resolve $host";</tt>\r
- $message = "can't resolve $host\n";\r
- }\r
-\r
- &main::debug( "dns - $host - $color, $summary" );\r
- return( $color, $summary, $message );\r
- }\r
-\r
- # I'm included perl code, I need this line.</tt>\r
- 1;\r
-\r
-Please note the final line. It is always required for a module file.\r
-\r
-=head1 SEE ALSO\r
-\r
-L<developer-guide>, L<spong-network>, L<spong.conf>\r
-\r
-=head1 AUTHOR\r
-\r
-Stephen L Johnson <F<sjohnson@monsters.org>>\r
-\r
-=head1 HISTORY\r
-\r
-Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong). Ed Hill\r
-original converted Big Brother (http://www.bb4.com) into Perl which diverged\r
-from Big Brother to become Spong. Ed Hill continued Spong development until\r
-version 2.1. Stephen L Johnson took over development in October, 1999 with his\r
-changes which became Spong 2.5.\r
-\r
+=head1 NAME
+
+spong-network-mod-template - A sample spong-network check module
+
+=head1 DESCRIPTION
+
+This document describes a sample plug-in module for the B<spong-network>
+program. Any modules that you create can be custom network checks, or they
+can be replacements for the core Spong modules.
+
+This template assumes that you are creating a network check called
+'dns'. The name of the file created should be 'check_dns'. The file name
+should always be 'check_' plus the registry name (e.g. for the foo check,
+the registry name is 'foo' and the file name is 'check_foo'.
+
+The line that has the assignment to $PLUGINS{'registry-name'} is the
+key to the registry mechanism. It's what ties the registry name to the
+the checking function.
+
+The registry name does not always have to match up to the service name as in
+the case of our module 'dns'. If you where creating a new and improved function
+to ping and traceroute, you could create a module called 'ping_trace'. You
+would use the registry name 'ping_trace', but you would use the service name
+'ping' in the C<E<amp>main::status()> function when reporting your information
+back to the server.
+
+check_dns:
+
+ # Register the routine with the plugin registry
+ $PLUGINS{'dns'} = \&check_dns;
+
+ # Check to see if they have the Net::DNS module installed, and if they do we
+ # can then do DNS queries, and see if DNS servers are alive.
+
+ eval "require Net::DNS;";
+ if( ! $@ ) { $dns = 1; } else { $dns = 0; }
+
+ # This check will (if the Net::DNS module is available) connect to a DNS
+ # server and ask that server to resolve it's own name. If it can do that,
+ # then we assume it is ok - If it can't then something is wrong.
+
+ sub check_dns {
+ my( $host ) = @_;
+ my( $color, $summary, $message ) = ( "green", "", "" );
+
+ if( ! $dns ) {
+ $summary = "can't do DNS lookups, Net::DNS not installed";
+ &main::debug( "dns - $host - $color, $summary" );
+ return ( "yellow", $summary,
+ "In order to do DNS queries you must install the Net::DNS " .
+ "Perl module.\nYou can find the module at your nearest CPAN " .
+ "archive or http://www.perl.com/CPAN/\n" )
+ }
+
+ my $resolver = new Net::DNS::Resolver;
+ $resolver->nameservers( $host );
+ $resolver->retrans(2);
+ $resolver->retry(1);
+ $resolver->recurse(0);
+ my $q = $resolver->search( $host, "A" );
+
+ if( defined $q && defined $q->answer && defined (($q->answer)[0]) ) {
+ $color = "green";
+ $summary = "dns ok";
+ } else {
+ $color = "red";
+ $summary = "can't resolve $host";
+ $message = "can't resolve $host\n";
+ }
+
+ &main::debug( "dns - $host - $color, $summary" );
+ return( $color, $summary, $message );
+ }
+
+ # I'm included perl code, I need this line.
+ 1;
+
+Please note the final line. It is always required for a module file.
+
+=head1 SEE ALSO
+
+L<developer-guide>, L<spong-network>, L<spong.conf>
+
+=head1 AUTHOR
+
+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 development until
+version 2.1. Stephen L Johnson took over development in October, 1999 with his
+changes which became Spong 2.5.
+
--- /dev/null
+#!@@PERL@@
+
+=head1 NAME
+
+B<spong-network> - report network service information to spong server.
+
+=head1 SYNOPSIS
+
+B<spong-network> [B<--debug> I<n>] [B<--kill|--restart|--nosleep|--refresh>]
+ [F<config_file>]
+
+=head1 DESCRIPTION
+
+This checks network connectivity and network service availability to various
+machines you want to monitor. It reports the status of the network services
+that it monitors to the spong server. Everything happens again after sleeping
+for a time period you have defined in your configuration file. This program
+typically runs on your spong server machine (although it can be run on any host
+- although I would suggest one with good network connectivity).
+
+The program checks a series of network services that are configured separately
+for each host. B<spong-network> also can be very aggressive in checking for
+network service that are down. You can configure multiple rechecks to guard
+against transitional failures.
+
+=head2 Running the program
+
+You should start this program in your system startup file, and it should be
+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 B<spong-network>
+process that is currently running that will cause it to reload it's
+configuration files. If you provide the B<--kill> flag, a signal will be sent
+to the running spong-client process causing it to exit.
+
+The B<--nosleep> or B<--refresh> flag causes the program to cycle through all
+of the checks once then exit. These flags can be used to run spong-client as a
+cron job (B<depreciated>), but it recommended that you run the program
+continuously.
+
+
+=head2 Format of update messages
+
+It sends a message for each check to the spong server and reports the
+following:
+
+=over 4
+
+=item * hostname (where is this report coming from)
+
+=item * service name ("disk", "cpu", "procs", "logs", "local")
+
+=item * color ("red", "yellow", "green")
+
+=item * a one line summary
+
+=item * a more detailed message providing additional detail.
+
+=back
+
+The color is determined by comparing the current status of that
+service against thresholds defined in the configuration file. If
+they are greater then the level you have defined for a warning, then the color
+is yellow. If they are greater then the critical level you have defined then
+the color is red.
+
+The one line summary provides information that might be useful at a glance when
+looking at the overall system status (such as a brief report on the load,
+number of users, and uptime).
+
+The more detailed message contains information such as the output of
+the ping command from the check ping module or the data read after testing
+a network service.
+
+=head2 Network Checks
+
+The check are actually a setup of modules that are called in series by
+B<spong-network>. Upon initialization, B<spong-network> will load the all of
+the modules that will be used from the F<LIBDIR/Spong/Network/plugins>
+directory. As each module is initialized, it registers itself with the plugins
+registry (see the L<Developer Guide|developer-guide>).
+
+The list of network checks and the order the are performed that are performed
+for a host are defined in the I<services> attribute of the host's entry in the
+L<%HOST|spong.hosts/"%HOSTS"> variable. The I<ping> service is appended by
+default to all of the lists of services to be check for a host. If the
+meta-service name of I<noping> is defined for a host, the ping check will no be
+done for the host.
+
+=head1 CONFIGURATION
+
+=head2 Configuration Files
+
+=over
+
+=item spong.conf
+
+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.
+
+=item spong.conf.[hostname]
+
+After reading the configuration file that you specify (or the default),
+it then reads the F<spong.conf.[hostname]> file where [hostname] is the
+hostname of the machine that you are running on. Since these configuration
+files are just standard perl code that gets imported, the variables that you
+define in the host specific config file will take precedence over the standard
+configuration settings.
+
+=item spong.hosts
+
+B<spong-network> reads all of the host that are to be check from the
+L<%HOSTS|spong.hosts/"%HOSTS"> variable in the L<spong.hosts> file. The
+list of services to be check for each host is already read from F<spong.hosts>.
+
+=back
+
+=head2 Configuration Variables
+
+From F<spong.conf>:
+
+=over
+
+=item $SPONGSLEEP, $SPONGSERVER, $SPONG_UPDATE_PORT
+
+Some basic spong configuration options that define how long to sleep (in
+seconds) before checking the status of a service again, the hostname of the
+spong server, and the port number that the spong server listens
+
+=item $SPONGSLEEP{'DEFAULT'}, $SPONGSLEEP{'spong-network'}
+
+This the new method for specifying the $SPONGSLEEP interval for Spong programs.
+If there is not $SPONGSLEEP{} entry for the program, it will use the
+I<$SPONGSLEEP{'DEFAULT'}> value. If no value is then found, B<spong-client>
+fall back to using $SPONGSLEEP.
+
+=item $SPONGTMP
+
+The directory that Spong programs use for temporary store and work files. It
+should be different a directory than F</tmp> for operation and security reasons.
+
+=item $SPONG_LOG_FILE
+
+If set to I<1>, B<spong-network> will log errors to a log file in I<$SPONGTMP>
+named F<spong-network.log>.
+
+=item $SPONG_LOG_SYSLOG
+
+If set to I<1>, B<spong-network> will log errors to the syslog using the
+I<USER> facility and the I<ERR> priority.
+
+=back
+
+From F<spong.hosts>:
+
+=over
+
+=item %HOSTS
+
+All of the host names defined in %HOSTS are the list of hosts that
+B<spong-network> will check. The services defined in the I<services> attribute
+are the list of services that will be check for each host. The I<ping> service
+is prepended to the list of services unless 'noping' is defined.
+
+=back
+
+=head1 FILES
+
+F<spong.conf>, F<spong.conf.hostname>, F<spong.hosts>
+
+=head1 DEPENDENCIES
+
+Perl v5.005_03 or greater is required.
+
+=head1 BUGS
+
+The check_dns module uses the Net::DNS Perl module. On some systems the
+Net::DNS module will fail and start reporting false DNS lookup failures. The
+cause is unknown at present. This will cause dns check for all hosts to fail
+and be reported as a critical status. The fix is to restart B<spong-network>
+(i.e. B<spong-network --restart> ),
+
+A work-around is to regularly do restart B<spong-network>, such as from a
+cron job.
+
+=head1 SEE ALSO
+
+L<spong-server>, L<spong.conf>, L<spong.hosts>,
+L<developer-guide>
+
+=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 development until
+version 2.1. Stephen L Johnson took over development in October, 1999 with his
+changes which became Spong 2.5.
+
+
-=head1 NAME\r
-\r
-spong-server-mod-tempate - how to build a spong-server data module\r
-\r
-=head1 DESCRIPTION\r
-\r
-This template will be a simple example that will write incoming 'cpu'\r
-status updates into a queueing directory. Each file will have the\r
-host's name plus the current time are it's file name. \r
-\r
-The file name of the module must begin with 'data_'. The registry key can\r
-be anything, but it should be consistent with the procedure's name. And the\r
-registry must be unique among the other loaded modules; otherwise, one\r
-module will overlay the other.\r
-\r
-The line that has the assignment to C<$DATAFUNCS{'registry-name'}> is the\r
-key to the registry mechanism. It's what ties the registry name to the\r
-your data module.\r
-\r
-data_cpu_queue:\r
-\r
- # Register the routine with the plugin registry\r
- $DATAFUNCS{'cpu_queue'} = \&data_cpu_queue;\r
-\r
- $CPU_QUEUE_DIR = "/var/spool/spong-queue"; # The spooling directory\r
-\r
- sub data_cpu_queue {\r
- my( $host, $service, $color, $start, $time, $sum, $message ) = @_;\r
-\r
- if ( $service ne 'cpu' ) { return; }\r
-\r
- my( $file ) = "$CPU_QUEUE_DIR/$host-" . time();\r
-\r
- if (! open(FH,"> $file") ) {\r
- &main::error("plugin::data_cpu_queue: Could not open file $file: $!");\r
- return;\r
- }\r
-\r
- print FH "hostname: $host\n";\r
- print FH "color: $color\n";\r
- print FH "start-time: $start\n";\r
- print FH "last-update: $time\n";\r
- print FH "summary: $sum\n";\r
- print FH "message:\n$message\n";\r
-\r
- close FH;\r
-\r
- &main::debug("plugin::data_cpu_queue: event written to file $file",5);\r
- }\r
-\r
- # I'm included perl code, I need this line.\r
- 1;\r
-\r
-Please note the final line. It is always required for a module file.\r
-\r
-You should use the C<E<amp>main::error()> function to log any error encountered\r
-in your module. The C<E<amp>main::error()> function is used to write output\r
-whenever something interesting happens in your module. \r
-\r
-Any configuration varirables needed for your data modules can be put into the\r
-Global section of your module as shown above. Of it can be added into the\r
-F<spong.conf> or F<spong.conf.E<lt>hostE<gt>> configuration files.\r
-Configuration variables for your module should be named to match them up\r
-with the name of your customized check. \r
-\r
-=head1 SEE ALSO\r
-\r
-L<developer-guide>, L<spong-server>, L<spong.conf>\r
-\r
-=head1 AUTHOR\r
-\r
-Stephen L Johnson <F<sjohnson@monsters.org>>\r
-\r
-=head1 HISTORY\r
-\r
-Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong). Ed Hill\r
-original converted Big Brother (http://www.bb4.com) into Perl which diverged\r
-from Big Brother to become Spong. Ed Hill continued Spong development until\r
-version 2.1. Stephen L Johnson took over development in October, 1999 with his\r
-changes which became Spong 2.5.\r
-\r
+=head1 NAME
+
+spong-server-mod-template - how to build a spong-server data module
+
+=head1 DESCRIPTION
+
+This template will be a simple example that will write incoming 'cpu'
+status updates into a queueing directory. Each file will have the
+host's name plus the current time are it's file name.
+
+The file name of the module must begin with 'data_'. The registry key can
+be anything, but it should be consistent with the procedure's name. And the
+registry must be unique among the other loaded modules; otherwise, one
+module will overlay the other.
+
+The line that has the assignment to C<$DATAFUNCS{'registry-name'}> is the
+key to the registry mechanism. It's what ties the registry name to the
+your data module.
+
+data_cpu_queue:
+
+ # Register the routine with the plugin registry
+ $DATAFUNCS{'cpu_queue'} = \&data_cpu_queue;
+
+ $CPU_QUEUE_DIR = "/var/spool/spong-queue"; # The spooling directory
+
+ sub data_cpu_queue {
+ my( $host, $service, $color, $start, $time, $sum, $message ) = @_;
+
+ if ( $service ne 'cpu' ) { return; }
+
+ my( $file ) = "$CPU_QUEUE_DIR/$host-" . time();
+
+ if (! open(FH,"> $file") ) {
+ &main::error("plugin::data_cpu_queue: Could not open file $file: $!");
+ return;
+ }
+
+ print FH "hostname: $host\n";
+ print FH "color: $color\n";
+ print FH "start-time: $start\n";
+ print FH "last-update: $time\n";
+ print FH "summary: $sum\n";
+ print FH "message:\n$message\n";
+
+ close FH;
+
+ &main::debug("plugin::data_cpu_queue: event written to file $file",5);
+ }
+
+ # I'm included perl code, I need this line.
+ 1;
+
+Please note the final line. It is always required for a module file.
+
+You should use the C<E<amp>main::error()> function to log any error encountered
+in your module. The C<E<amp>main::error()> function is used to write output
+whenever something interesting happens in your module.
+
+Any configuration variables needed for your data modules can be put into the
+Global section of your module as shown above. Of it can be added into the
+F<spong.conf> or F<spong.conf.E<lt>hostE<gt>> configuration files.
+Configuration variables for your module should be named to match them up
+with the name of your customized check.
+
+=head1 SEE ALSO
+
+L<developer-guide>, L<spong-server>, L<spong.conf>
+
+=head1 AUTHOR
+
+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 development until
+version 2.1. Stephen L Johnson took over development in October, 1999 with his
+changes which became Spong 2.5.
+
--- /dev/null
+=head1 NAME
+
+B<spong-server> - save status information reported by spong programs
+
+=head1 SYNOPSIS
+
+B<spong-server> [B<--debug> I<n>] [B<--kill|--restart>] [F<config_file>]
+
+=head1 DESCRIPTION
+
+The B<spong-server> is the central core program of Spong. The program received
+status reports from various spong clients (specifically B<spong-network> and
+various B<spong-client> program running). If the message is worth notifying
+someone about, it calls the B<spong-message> program. The status messages
+messages are stored into an internal database with significant changes being
+logged into a history event log. Queries from spong interface programs (like
+B<spong> and B<www-spong>) seeking to display the data in the B<spong-server>
+database.
+
+=head2 Running the program
+
+You should start this program in you system startup file, and it should be
+running constantly. If no parameters are provided, B<spong-server> will
+fork and detach itself from the console to run as a daemon.
+
+If you provide the B<--debug> I<n> flag then debugging information will be
+printed to stderr. The I<n> is an integer from 1 to 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
+B<spong-server> process that is currently running. It will release reload it's
+configuration and restart. If the B<--kill> flag if provided, a signal will
+be sent to the running B<spong-server> process causing it to exit.
+
+An alternate configuration file can be specified on the command line. This
+file will be read instead of the default F<spong.conf> configuration file.
+
+=head2 Theory of Operation
+
+The B<spong-server> has a main process that spawns a number of child processes
+to handle all of the work. There are a query process which handles queries into
+the Spong database, an update process which handles Spong formatted update
+messages (see L<developer-guide/"SPONG PROTOCOL">), a BBSERVER
+update process which handled Big Brother client update messages, and possibly
+other process are more feature are added in the future. The main process
+monitors each of the child processes. It will restart any child process that
+dies for any reason.
+
+Each time a connection comes in, the child process is forks off to handle the
+the above tasks. The main child process goes back to waiting for more
+connections.
+
+=head2 Data Modules
+
+The B<spong-server> has a plug-in module facility similar to the other
+Spong programs. One or more modules can be installed in the
+F<LIBDIR/Spong/plugins/> directory. The modules are loaded are run-time by
+B<spong-server>. As each module is initialized is registers itself with
+the plug-ins registry.
+
+Each module is called in turn after all of the normal processing is done for
+incoming status messages. This allows you access to data of a status message
+that will eventually be discarded. Data modules can do virtually anything that
+you desire with the incoming data. The data can be written to a log or
+database or feed to another application for further filter or processing.
+
+Two sample data modules are located in the F<contrib/plugins/spong-server>
+directory of the Spong distribution. The two modules (B<data_rrd_disk> and
+B<data_rrd_la> work in conjunction with a software package named RRD Tool to
+log disk and cpu information into Round Robin Databases. The modules are
+included as examples. They are not of must use by themselves. See the
+B<Spong-RRD> package (http://spong.sourceforge.net/downloads.html) for a
+complete package that utilizes data modules.
+
+=head2 Big Brother (BBSERVER) Emulation
+
+=head1 CONFIGURATION
+
+=head2 Configuration Files
+
+=over
+
+=item spong.conf
+
+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.
+
+=item spong.conf.[hostname]
+
+After reading the configuration file that you specify (or the default),
+it then reads the F<spong.conf.[hostname]> file where [hostname] is the
+hostname of the machine that you are running on. Since these configuration
+files are just standard perl code that gets imported, the variables that you
+define in the host specific config file will take precedence over the standard
+configuration settings.
+
+=item spong.hosts
+
+B<spong-server> reads all of the host that are defined in the
+L<%HOSTS|spong.hosts/"%HOSTS"> variable in the L<spong.hosts> file.
+B<spong-server> uses this list of servers to validate incoming status and
+control messages. And the list is used in format of database queries.
+
+=item spong.groups
+
+The L<spong.groups> file defines groups of hosts. B<spong-server> uses these
+host groups to filter and format the data returned in database queries.
+
+=back
+
+From F<spong.conf>:
+
+
+Yes there are a lot of variables. But all of the variables have defined
+default values. Most of these variables are used customizing the client
+web and text interfaces.
+
+=over
+
+=item $SPONG_UPDATE_PORT
+
+This variable defines the port that the Spong update process listens on. If
+This variable is not defined the Spong update process will not be started.
+The default value is 1998.
+
+=item $SPONG_UPDATE_PORT
+
+This variable defines the port that the Spong query process listens on. If
+this variable is not defined the Spong query process will not be started. The
+default value is 1999.
+
+=item $SPONG_BB_UPDATE_PORT
+
+This variable defines the port that the Big Brother BBSERVER emulation
+process listens on. If this variable is not defined the Big Brother BBSERVER
+emulation process will not be started. The default value is 1984.
+
+=item $SPONGSLEEP (Depreciated)
+
+This variable is used by B<spong-server> to determine how old a service
+status can be before it is considered stale. It's status will be reported
+as 'purple'. The exact time to live a message is 2 * $SPONGSLEEP. (This
+variable is depreciated in favor of the new $SPONGSLEEP{} variables.)
+
+=item $SPONGSLEEP{'DEFAULT'}, $SPONGSLEEP{'spong-server'}
+
+This the new method for specifying the $SPONGSLEEP interval for Spong programs.
+If there is not $SPONGSLEEP{} entry for the program, it will use the
+I<$SPONGSLEEP{'DEFAULT'}> value. If no value is then found, B<spong-client>
+fall back to using $SPONGSLEEP.
+
+=item $SPONGDB
+
+This defined the directory where the Spong database will be stored. Each host
+will have a subdirectory in this directory which is named for the host.
+
+=item $SPONGTMP
+
+The directory that Spong programs use for temporary store and work files. It
+should be different a directory than F</tmp> for operation and security reasons.
+
+=item $SPONGSTATUS
+
+If this variable is set to 1, it will enable the storing of the update
+status message information for each event that is generated in the history
+log. This status message information is access via the web interface by
+click on the status color or icon link of an event in a History Listing.
+
+=item $SPONG_LOG_FILE
+
+If set to I<1>, B<spong-network> will log errors to a log file in I<$SPONGTMP>
+named F<spong-network.log>.
+
+=item $SPONG_LOG_SYSLOG
+
+If set to I<1>, B<spong-network> will log errors to the syslog using the
+I<USER> facility and the I<ERR> priority.
+
+=item $SPONG_SERVER_ALARM
+
+This variable defined the maximum amount of time (in seconds) that a incoming
+connection of a status message can last. Once the time limit is exceeded
+B<spong-server> will terminated the connection. This action can be disables
+by setting the variable to zero (0).
+
+=item $WWW_FQDN
+
+Set this variable to 1 to display the fully qualified domain name (FQDN) of
+hosts in Spong client displays. Otherwise only the first element of the FQDN
+will be displayed.
+
+=back
+
+From F<spong.hosts>:
+
+=over
+
+=item %HOSTS
+
+All of the host names defined in %HOSTS are the list of hosts that
+B<spong-server> will accept status messages for. Any status message for an
+unknown host will be logged as an error and discarded.
+
+=back
+
+From F<spong.groups>:
+
+=over
+
+=item %GROUPS
+
+The host groups that are defined in this variable are used to filter and
+format data queries of the Spong database.
+
+=back
+
+=head1 FILES
+
+F<spong.conf>, F<spong.conf.hostname>, F<spong.hosts>, F<spong.groups>
+
+=head1 DEPENDENCIES
+
+Perl v5.005_03 or greater is required.
+
+=head1 BUGS
+
+No know bugs.
+
+=head1 SEE ALSO
+
+L<spong.conf>, L<spong.hosts>, L<spong.groups>, L<spong-server-mod-template>,
+L<developer-guide>
+
+=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 development until
+version 2.1. Stephen L Johnson took over development in October, 1999 with his
+changes which became Spong 2.5.
+
+
imported by each of the spong programs
The variables are grouped by the spong programs. Each section will list the
-varirables that are used in the program along with the meaning of the
+variables that are used in the program along with the meaning of the
variable to the program.
=head2 All programs
-This sections deals with varirables that are used by all of the spongs
+This sections deals with variables that are used by all of the Spong
programs. Any differences in how the programs use the variable will be detailed in the I<"Configuration Variables"> section of the program's documentation.
=over
This variable holds the amount in time in seconds) that spong client programs
(i.e. B<spong-client> and B<spong-network>) are expected to sleep between
checking cycles. For B<spong-server> this is the time to live for statuses. If
-a tatus has not been updated in 2 * $SPONGSLEEP seconds it is considered to be
+a status has not been updated in 2 * $SPONGSLEEP seconds it is considered to be
old and the color is set to 'purple'. For www-spong, $SPONGSLEEP represents the
amount of time to automatically refresh the web page.
=item $SPONG_QUERY_PORT
-This varirable defines the port that the L<spong-server> query process listens
-on. If this varirable is not defined on the I<$SPONGSERVER> host, the
+This variable defines the port that the L<spong-server> query process listens
+on. If this variable is not defined on the I<$SPONGSERVER> host, the
L<spong-server> query process will not be started. The default value is 1999.
=item $SPONG_BB_UPDATE_PORT
This variable defines the port that the Big Brother BBSERVER emulation process
listens on. If this variable is not defined on the I<$SPONGSERVER> host, the
-Big Brother BBSERVER emluation process will not be started. The default value
+Big Brother BBSERVER emulation process will not be started. The default value
is 1984.
=item $SPONGTMP
B<spong-message> is called for every time a system or service reports a
problem. If its value is ``CHANGE'', then B<spong-message> is only called when
there is a change of state . If this values is ``RED-CHANGE'', then
-B<spong-message> is called; everytime a system of service reported a problem
+B<spong-message> is called; every time 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> is never called.
=over
+=item $WWW_USE_IMAGES
+
+The variable controls how services status colors are displayed on the web
+displays. If set to 1, service status colors are represented by colored icons.
+Otherwise the colors are represented by blocks of color.
+
+The default value is 0. If B<$WWW_USE_IMAGES> is set, the L<"$WWWGIFS">
+variable must set to the location of the images directory.
+
=item $WWWGIFS
-This L<$WWW_USE_IMAGES> is set to 1, this variable should be set to the
-URL path of the F<www/gifs> directory with the document tree of the web
-server.
+When L<"$WWW_USE_IMAGES"> is set to 1, this variable should be
+set to the URL path of the F<www/gifs> directory with the document tree of the
+web server.
=item $WWWHTML
The variable defined HTML code that will be appended to the Action Bar at
the top of Host Displays in the right frame of the web client interface. This
code is eval'ed before display. You can include perl code and variables. The
-perl varirable C<$name> holds the FQDN of the host being displayed.
+perl variable C<$name> holds the FQDN of the host being displayed.
=item $WWW_PROB_ACTIONBAR
-This variable is similar in function to the $WWW_ACTIONBAR_CUSTOM varirable.
+This variable is similar in function to the $WWW_ACTIONBAR_CUSTOM variable.
Except this action bar is display after each host listed in the problem
frame (left) of the client web interface.
=item $WWW_TITLE_ACTIONBAR
-This varirable can host HTML code that will be appended to the action bar
+This variable can host HTML code that will be appended to the action bar
that is display in the title (top) frame of the client web display. This
code is eval'ed before display. You can include perl code and variables. This
action bar is only displays if L<$WWWFRAMES> is set to 3.
=item $WWW_TITLE_COLOR
-Defines the background color for table title cells in the client web inerface.
+Defines the background color for table title cells in the client web interface.
The colors are defined in the HTML color format.
=item $WWW_CELL_COLOR
-This varirable defined the background color for normal table cells in the
-client web interface. The colors are definedin the HTML color format.
+This variable defined the background color for normal table cells in the
+client web interface. The colors are defined in the HTML color format.
=item $WWW_COLOR{...}
=item @WWW_REFRESH_ALLOW
A list of Perl regular expressions that are checked against the REMOTE_ADDR,
-REMOTE_HOST and REMOTE_USER enviornmental CGI varables. If there is a match on
+REMOTE_HOST and REMOTE_USER environmental CGI parables. If there is a match on
any of these variables L<www-spong> will attach a REFRESH meta tag to reload
-the web pages every L<$SPONGSLEEP> seconds. See the L<Administrator
-Guide|admin-guide/"Autorefresh"> for more details.
+the web pages every L<$SPONGSLEEP> seconds. See the
+L<admin-guide/"$WWW_REFRESH Logic"> for more details.
=item @WWW_REFRESH_DENY
A list of Perl regular expressions that are checked against the REMOTE_ADDR,
-REMOTE_HOST and REMOTE_USER enviornmental CGI varables. If there is a match on
+REMOTE_HOST and REMOTE_USER environmental CGI parables. If there is a match on
any of these variables, L<www-spong> will NOT attach a REFRESH meta tag. User's
-must use the Reload/Refresh button on their web broswer to update the Spong web
-pages. See the L<Administrator Guide|admin-guide/"Autorefresh"> for more
+must use the Reload/Refresh button on their web browser to update the Spong web
+pages. See the L<admin-guide/"$WWW_REFRESH Logic"> for more
details.
+=item @WWWCONTACT
+
+This is a partial URL to a CGI script that can do paging for systems. If it is
+used a "Contact" link will appear on Tool Bar on Spong Web Displays. Refer to
+the L<User Guide|user-guide> for more details.
+
+There not sample CGI script provided. To create please see
+L<admin-guide/"Custom Contacts">. The variable is commented out and is not used
+by default.
+
=back
=head2 www-spong-ack
=over
-=back
-
=item @DFIGNORE
A list of regular expression strings that are matched against the raw file
host is running on. By default the value is 80, but this can be overridden on a
host by host basis.
+=back
+
=head2 spong-message
=over
=head2 OS SPECIFIC VARIABLES
These are various external programs that Spong uses to gather system
-informationto evaluate in it's checks. It is I<strongly>> recommended that you
-use the full path names for the values of these varirables.
+information to evaluate in it's checks. It is I<strongly>> recommended that you
+use the full path names for the values of these variables.
=over
=head1 FILES
-=over
+=over 4
=item F<SPONGHOME/etc/spong.conf>
read after the standard spong.conf file is read. Since the configuration
files are just Perl code, anything you set in the host specific spong.conf
file will override the standard configuration file. ``host'' can be either
-the full hostname of the machine you are running on (strobe.weeg.uiowa.edu),
-or just the name minus the domain (strobe). It looks for the full name
+the full host name of the machine you are running on (web1.school.edu),
+or just the name minus the domain (web1). It looks for the full name
first, and then if it can not find it - it looks for the shorter name.
+=back
+
=head1 SEE ALSO
L<perl> , L<spong-server>, L<spong-network>, , L<spong-client>, L<www-spong>,
-L<www-spong-ack>, L<spong-cleanup>, L<spong-message>
+L<www-spong-ack>, L<spong-cleanup>, L<spong-message>, L<POSIX/"strftime">
=head1 AUTHOR
=item * compress
-This attribute indiciates whether or not empty empty service columns should
+This attribute indicates whether or not empty empty service columns should
be removed when displaying this groups. Otherwise all of the services in
the Spong database will be shown. This attribute should be 0 or 1. The default
value is 0 (don't compress).
=back
-=HEAD1 FORMAT
+=head1 FORMAT
The F<spong.conf> file is simply Perl code that gets imported by each Spong
program, so the only real format restrictions is just what is syntactically
members => ['godzilla.monsters.org',
'ghidora.monsters.org.',
],
- display => 0; # Don't display this groups
+ display => 0; # Don't display this group
);
=head1 SEE ALSO
-the <i>spong-server</i> manpage , the <i>spong-network</i> manpage , the
-<i>spong-message</i> manpage
-<p>
-<hr>
-<h1>
-<a NAME="spong.hosts_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
-<p>Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong).
-</body>
-</html>
+L<spong-server>, L<spong-network>, L<spong-message>
+
+=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 development until
+version 2.1. Stephen L Johnson took over development in October, 1999 with his
+changes which became Spong 2.5.
+
=back
The services is a string listing the network modules to run against the host
-seperated by spaces. The list of network modules included with Spong is contactly growing, but they include ``dns'' (if you have the
-Net::DNS Perl module installed), ``ftp'', ``smtp'', ``http'', ``imap'',
-``pop3'', ``nntp'', ``nfs'',``ntp'' and ``ssh''. The list can include any
-addition network checks that you have developed (see L<spong-network</b> and
-L<developer-guide> for more details) . Any host listed is automatically checked
-for network connectivity (via ping). The metaservice ``noping'' can be included
-in the list of modules to cause B<spong-network> to skip the 'ping' test.
+separated by spaces. The list of network modules included with Spong is
+constantly growing, but they include ``dns'' , ``ftp'', ``smtp'', ``http'',
+``imap'', ``pop3'', ``nntp'', ``nfs'',``ntp'' and ``ssh''. The list can
+include any addition network checks that you have developed (see
+L<spong-network> and L<developer-guide> for more details) . Any host listed
+is automatically checked for network connectivity (via ping). The meta-service
+``noping'' can be included in the list of modules to cause B<spong-network> to
+skip the ``ping'' test.
The I<down> attribute is a list of ``downtimes''. It is a list (well reference
to one anyway) of one or more strings in the following format -
address that the machine responds to.
Additional attributes can be added into I<%HOSTS> entries. These attributes
-can be used for any external program of additional modudules that you have
+can be used for any external program of additional modules that you have
added to your Spong installation. All of the Spong programs will ignore any
attributes that they don't recognize.
=item * alltelsms
-phone number of a phone subscribered to Alltel Communications SMS service.
+phone number of a phone subscriber to Alltel Communications SMS service.
=item * teletouch
=item * teletouch_short
-teletouch pages numer for small alpha pagers
+teletouch pager number for small alpha pagers
=back
-These attributes are messaging modules names for sending out notifictions to
-people. All of the messing modules are loaded by B<spong-message> as a plugin
+These attributes are messaging modules names for sending out notifications to
+people. All of the messing modules are loaded by B<spong-message> as a plug-in
modules. The attributes listed above are the messaging modules that are part of
the current Spong distribution. New messaging modules can be easily be
developed. See L<spong-message> and the L<developer-guide> for more details).
-=HEAD1 FORMAT
+=head1 FORMAT
The F<spong.conf> file is simply Perl code that gets imported by each spong
program, so the only real format restrictions is just what is syntactically
First, the HUMANS. The following describes the <%HUMANS> hash.
-<pre> %HUMANS = ( [stanza], [stanza], [stanza] );</pre>
+ %HUMANS = ( [stanza], [stanza], [stanza] );
+
where [stanza] is a second hash, that looks like the following:
-<pre> 'unix-staff' => { name => 'Midrange On-call Staff',
- email => 'its-unix@uiowa.edu',
+ 'unix-staff' => { name => 'Midrange On-call Staff',
+ email => 'unix-staff@school.edu',
+ skytel => '1234567' },
- skytel => '1234567' },</pre>
What this says is that the 'unix-staff' human has the following attributes
-(name = Midrange On-call Staff, email = <a href="MAILTO:its-unix@uiowa.edu">its-unix@uiowa.edu</a>,
-skytel = 1234567).
-<p>Now, the HOSTS. The following describes the <b>%HOSTS</b> hash.
-<pre> %HOSTS = ( [stanza], [stanza], [stanza] );</pre>
+(name = Midrange On-call Staff, email = unix-statff@school.edu, skytel =
+1234567).
+
+Now, the HOSTS. The following describes the B<%HOSTS> hash.
+
+ %HOSTS = ( [stanza], [stanza], [stanza] );
+
where [stanza] is a second hash, that looks like the following:
-<pre> 'www.uiowa.edu' => { services => 'ftp smtp http',
- ip_addr => ['192.168.15.2','10.2.124.200'],</pre>
+ 'www.uiowa.edu' => { services => 'ftp smtp http',
+ ip_addr => ['192.168.15.2','10.2.124.200'],
+ down => [ '*:0015-0030','6:23:00-23:59']
+ },
-<pre> down => [ '*:0015-0030','6:23:00-23:59'] }</pre>
What this says is that the 'www.uiowa.edu' host has the following attributes
-(services = ftp smtp http; ip address=192.168.15.2 and 10.2.124.200;
+(services = ftp smtp http; ip address=192.168.15.2 and 10.2.124.200;
and down time of 12:15AM-12:30AM every day and from 11:00PM-12:00PM on
Saturdays).
-<p>I know the format can be a little odd at first, but I chose it because
+
+I know the format can be a little odd at first, but I chose it because
of both its simplicity to work with in the code (I don't have to parse
anything - Perl does all the work), and because it is easy to extend -
adding additional attributes is quite straightforward.
-<p>
-<hr>
-<h1>
-<a NAME="spong.hosts_examples_0"></a>EXAMPLES</h1>
-Here are some lines from our spong.hosts file to show you possible configurations.
-<pre> %HUMANS = (
- 'unix-staff' => { name => 'Midrange On-call Staff',
+=head1 EXAMPLES</h1>
- email => 'its-unix@school.edu',
+Here are some lines from our spong.hosts file to show you possible
+configurations.
-
+ %HUMANS = (
+ 'unix-staff' => { name => 'Midrange On-call Staff',
+ email => 'admin-staff@school.edu', },
- 'edhill' => { name => 'Ed Hill',
+ 'edhill' => { name => 'Ed Hill',
+ email => 'ed-hill@school.edu',
+ skytel => '1234567' },
- email => 'ed-hill@school.edu',
+ );
- skytel => '1234567' },
+ %HOSTS = (
- );
+ 'strobe.weeg.school.edu' =>; { services => 'dns ftp smtp http',
+ ip_addr => [ '192.168.15.2',
+ '10.2.124.200' ],
+ down => [ "*:05:30-06:30",
+ "0:00:00-04:00 ] },
- %HOSTS = (
+ 'www.school.edu' => { services => 'ftp smtp http' },
- 'strobe.weeg.school.edu' => { services => 'dns ftp smtp http',
+ );
- ip_addr => [ '128.255.1.3',
-
- '128.255.64.3' ],
-
- down => [ "*:05:30-06:30",
-
- "0:00:00-04:00 ] },
+=head1 COMPARABILITY
+In a future release of spong the %HUMAN configuration information will
+be moved into the spong.message configuration file. It is currently being
+retained in the spong.hosts file for compatibility.
- 'www.school.edu' => { services => 'ftp smtp http' },
+=head1 SEE ALSO
- );
+L<spong-server>, L<spong-network>, L<spong-message>
+=head1 AUTHOR
+Ed Hill <F<ed-hill@uiowa.edu>>, Unix System Administrator, The University of
+Iowa
+Stephen L Johnson <F<sjohnson@monsters.org>>
-</pre>
+=head1 HISTORY
-<h1>
+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 development until
+version 2.1. Stephen L Johnson took over development in October, 1999 with his
+changes which became Spong 2.5.
-<hr WIDTH="100%">COMPATABILITY</h1>
-In a future release of spong the %HUMAN configuration information will
-be moved into the spong.message configuration file. It is currenly being
-retained in the spong.hosts file for compatability.
-<br>
-<hr>
-<h1>
-<a NAME="spong.hosts_see_0"></a>SEE ALSO</h1>
-the <i>spong-server</i> manpage , the <i>spong-network</i> manpage , the
-<i>spong-message</i> manpage
-<p>
-<hr>
-<h1>
-<a NAME="spong.hosts_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
-<p>Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong).
-</body>
-</html>
=head1 DESCRIPTION
The F<spong.message> file defines the rules that B<spong-message> program used
-for notifications. The rules consist of attributes which define crieria
+for notifications. The rules consist of attributes which define criteria
which events are matched against and a list of contacts to notify if all
of the matching criteria are met.
=item * exclude_services
A list of one or more regular expressions that are matched against the host
-name of the status event. If at leat one of the expressions matched the service
+name of the status event. If at least one of the expressions matched the service
name, the term is considered an exclusion match..
=item * exclude_host_groups
attributes.
The I<days> attributes are a list of strings with the following format -
-'d' or 'd-d'. Where d is the day of the where (0-6, 0=Sunday, 6=Staurday).
+'d' or 'd-d'. Where d is the day of the where (0-6, 0=Sunday, 6=Saturday).
And 'd-d' represents a range of days (i.e. 1-5 = Monday - Friday).
The I<times> attributes are a list of string with the following format -
entry from the %HUMANS defined in F<spong.hosts>
and func is one of the message module attributes defined for that human.
-A contact entry can also be a stanza The stanza must have a rcpt attribute
+A contact entry can also be a stanza The stanza must have a 'rcpt' attribute
which is a I<contact> strings as defined above (i.e. 'human' or 'human:func').
It can also have an optional I<delay> and/or I<repeat> attribute. The I<delay>
attribute is the duration, in seconds, that an event be in an alert status
],
},
-The <b>$RULES_MATCH</b> variable has three possible values:
+The B<$RULES_MATCH> variable has three possible values:
+
=over
=item B<OLD>
Use Spong ver 2.1 messaging. Send notification the human defined in the
-contact attibute for the host name of the message.
+contact attribute for the host name of the message.
=item B<FIRST-MATCH>
Rules are checked into order. All matching rules are processed.
-=over
+=back
I know the format can be a little odd at first and overwhelming at first, but I
chose it because of both its simplicity to work with in the code (I don't have
=head1 MESSAGE TEMPLATES
Notification messages formats are determined by the templates in the
-C<%TEMPLATES> variable in the F<spong.message> file. Templates are seached
+C<%TEMPLATES> variable in the F<spong.message> file. Templates are searched
according to the following order: 'contact:module', 'module', 'contact',
'DEFAULT'.
Any text in a template string is added verbatim to the message. The list of
-substituation variables can be added to the template strings.
+substitution variables can be added to the template strings.
=over
=item !!WWWSPONG!!
-The $WWWSPONG url variable from the F<spong.conf> configuration variable.
+The $WWWSPONG URL variable from the F<spong.conf> configuration variable.
=item !!SUMMARY!!
=item !!DETAILED!!
The detailed message field of the status message. The value of this variable
-can be very large and have multple lines of text.
+can be very large and have multiple lines of text.
=item !!CURTIME!!
=item !!TIME!!
-The date of the event message formmated according to $TIMEFMT
+The date of the event message formated according to $TIMEFMT
=item !!DATETIME!!
-The date/time of the event message formateed according to $DATETIMEFMT
+The date/time of the event message formatted according to $DATETIMEFMT
=back
=head1 MATCHING LOGIC
The primary factor of how spong.message rules are processed depends upon the
-vaule of I<$RULES_MATCH>. If set to 'OLD' then the rules are not used at all.
-B<spong-message> reverts back to it Spong version 2.1 behaviour. Notify the
+value of I<$RULES_MATCH>. If set to 'OLD' then the rules are not used at all.
+B<spong-message> reverts back to it Spong version 2.1 behavior. Notify the
human defined in the contact attribute of the <b>%HOSTS</b> entry for the host.
This functionality included for backwards compatibility and to aid in migrating old Spong vers 2.0 and Spong 2.1 installations to the current version. It will
rule, that rule will match any host name.
The I<exclude_hosts>, I<exclude_services>, and I<exclude_host_groups> terms
-have a slightly different matching behaviour man the others. If there is a
+have a slightly different matching behavior man the others. If there is a
match against any of them, the rule will not match even if all of the other
terms match. For example, if a rules has B<hosts => [ '.*.cic.my-company',
'.*.corp.my-company.com' ]> and B<exclude_hosts[ 'my-pc' ]>, a host name of
];
-=head1 COMPATABILITY</h1>
+=head1 COMPATIBILITY
-To use Spong version 2.1 iB<spong-message> and messaging configurations set
-I<$RULES_MATCH> to 'OLD'. If <b>$RULES_MATCH</b> is not defined it will default
+To use Spong version 2.1 B<spong-message> and messaging configurations set
+I<$RULES_MATCH> to 'OLD'. If B<$RULES_MATCH> is not defined it will default
to 'OLD'.
=head1 SEE ALSO
-L<spong-messsage>, L<spong.hosts>, L<spong.groups>
+L<spong-message>, L<spong.hosts>, L<spong.groups>
=head1 AUTHOR
=head1 NAME
-spongfaq - frequently asked questions about Spong ($Revision: 1.1 $, $Date: 2000/05/26 19:25:57 $)
+spongfaq - frequently asked questions about Spong ($Revision: 1.2 $, $Date: 2000/09/12 19:21:00 $)
=head1 DESCRIPTION
=item * history of problems
-=item * verbose information to help diagnosis problems</li>
+=item * verbose information to help diagnosis problems
=back
It should print out you the fully qualified domain name of your system.
This should match the hostname configured in the song.hosts file on the
-spong-server macine. If they don't match then you can do 1 of 2 things.
-
+spong-server machine. If they don't match then you can do 1 of 2 things.
In your hosts file make use that the full domain name is the first name
of your host's line. i.e.
192.168.2.34 my-host.inkcom.com my-host
-
Or put if your system is in your DNS server properly, make sure that 'dns' is
in front of 'file' on the hosts: line of the /etc/nsswitch.conf file.
-There a utility L<gethost-test> in the F</utils/> directory of
+There a utility B<gethost-test> in the F</utils/> directory of
the Spong distribution. You can run it on a machine to make sure that it
is setup correctly to resolve it's full quality domain name. The utility
is run by enter the following command C<perl gethost-test>.
+If none of the above works or can't make the changes, you still have one last
+resort. The F<spong.conf> and F<spong.conf.E<lt>hostnameE<gt>> file are loaded
+after the $HOST variable is assigned. That mean that you can override the
+calculated $HOST hostname. Just added at '$HOST = "desired host name";'
+statement in either of the F<spong.conf> or F<spong.conf.E<lt>hostnameE<gt>>
+files.
+
=head2 3. How do I get e-mail/paging/alpha paging/notifications to work?
The most important thing is to go through the L<spong.conf>, L<spong.hosts>,
-and L<spong.message> configuration files. And be sure to read the documention
+and L<spong.message> configuration files. And be sure to read the documentation
for L<spong.conf>, L<spong.hosts> L<spong.message>, configuration files and the
L<spong-message> and L<spong-server> programs.
If you are still having problems, follow the check list below to help
resolve your problem.
+=over
+
=item 1. $SEND_MESSAGE in spong.conf
In spong.conf make sure the $SEND_MESSAGE is set to 'RED', 'CHANGE' or
--- /dev/null
+=head1 NAME
+
+B<www-spong-ack> - WWW (CGI) based spong acknowledgment tool
+
+=head1 SYNOPSIS
+
+http://spong-server.my-inc.com/spong/www-spong-ack
+
+=head1 DESCRIPTION
+
+Then a spong event occurs (or will occur), you can use this tool to acknowledge
+that your know there is a problem. You can provide text that will be seen by
+others looking at the event (via a spong display program). You can specify a
+time limit that the problem will occur. If a problem has been acknowledged,
+you will no longer receive notifications of the problem, and the spong display
+programs will show the of the service(s) as "blue".
+
+=head2 Theory of Operation
+
+The B<www-spong-ack> program is designed to interact with the L<www-spong>
+Spong display program, but it the program can be used if it is invoked directly.
+
+When the program is initially invoked it will list all of the acknowledgments at
+the top of the page in the "Current Acknowledgments" section. The host/service
+and the expiration date/time of the acks are displayed. A I<Delete> link is
+provided for every ack. that will delete that particular ack. when selected.
+
+Below in the "New Acknowledgment" section is a form form for creating a new
+acknowledgment. The host name is selected from the drop-down box. The service(s)
+to be acknowledged is entered in service field. The duration of the event is
+entered in one of several formats into the duration field. Your e-mail address
+should be entered into the e-mail address field. It is only used to show who
+created the ack. And a message about the acknowledgement can be entered. Once
+all of the information is entered, press the 'Create' button to create the
+acknowledgement.
+
+=head1 CONFIGURATION
+
+=head2 Configuration Files
+
+B<spong-cleanup> reads the standard spong.conf and spong.conf.E<lt>hostE<gt>
+configuration files.
+
+=head2 Configuration Variables
+
+=over
+
+=item $SPONGSERVER
+
+The host that at least the L<spong-server> and L<spong-message>
+programs are running on. Typically the L<spong-network> program runs on that
+host as well.
+
+=item $SPONG_UPDATE_PORT
+
+This variable defines the port that the L<spong-server> update process listens
+on. If this variable is not defined on the I<$SPONGSERVER> host, the
+L<spong-server> update process will not be started. The default value is 1998.
+
+=back
+
+=head1 FILES
+
+F<SPONGHOME/etc/spong.conf>, F<SPONGHOME/etc/spong.conf.E<lt>hostE<gt>>
+
+=head1 DEPENDENCIES
+
+Perl v5.005_03 or greater is required.
+
+A working web server that can run CGI programs.
+
+=head1 BUGS
+
+No know bugs.
+
+=head1 SEE ALSO
+
+L<spong-server>, L<spong-ack>, L<spong.conf>, L<user-guide>
+
+=head1 AUTHOR
+
+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 development until
+version 2.1. Stephen L Johnson took over development in October, 1999 with his
+changes which became Spong 2.5.
+
--- /dev/null
+#!@@PERL@@
+
+=head1 NAME
+
+B<www-spong> - display spong system status via the web or general static HTML
+pages of system status
+
+=head1 SYNOPSIS
+
+B<www-spong> [
+ S<B<--summary> [I<hostlist>] |>
+ S<B<--problems> [I<hostlist>] |>
+ S<B<--history> [<hostlist>] |>
+ S<B<--host> I<host> |>
+ S<B<--services> I<host> |>
+ S<B<--stats> I<host> |>
+ S<B<--config> I<host> |>
+ S<B<--info> I< host> |>
+ S<B<--service> I<host:service>>
+ ]
+ S<[--brief | --standard | --full ]>
+
+=head1 DESCRIPTION
+
+The B<www-spong> program interfaces with the spong-server to display the
+collected information in HTML format. B<www-spong> can be run in two modes: as
+a CGI program and from the command line.
+
+When run as a CGI program it does not have to loaded onto the same machine that
+spong-server is running. It queries the spong-server through it's query port.
+it will display information via a web page that reloads itself at regular
+intervals. When run with no parameters it created a page with two or three
+frames. In tree frames mode there will be a top title frame spanning the entire
+page that has an action bar to switch views. The remain frames are displayed
+below. The left frame displays a summary of systems along with their
+associated problems (services that are red). The right panel is a table that
+lists the hosts and services, and the current status is a colored block or an
+icon depending on how spong-server is configured. For further information on
+how to use the web interface see <Users Guide|user-guide>.
+
+When run from a command line, www-spong generates HTML pages that are printed
+to the console. This mode can be used to generate static HTML pages. If
+www-spong is run without any parameters a page that contains a summary display
+for all hosts is generated.
+
+=head1 OPTIONS
+
+=over
+
+=item B<--summary> [I<hostlist>]
+
+Summarize the status of hosts, in hostlist, in a table that lists
+the hosts and services, and the current status is a colored block or an
+icon depending on how spong-server is configured. If hostlist if not specified
+all hosts defined in spong.hosts are displayed.
+
+=item B<--grp-summary>
+
+Summary the status of all by Host Groups defined in the L<spong.groups> file.
+Each Host Group is displayed in a table that lists the hosts and services, and
+the current status is a colored block or an icon depending on how spong-server
+is configured.
+
+=item B<--problems> [I<hostlist>]
+
+Shows a summary of all the problems (services that are red) for the all
+the hosts in hostlist. If hostlist is not specified, all hosts defined
+in spong.hosts are displayed.
+
+=item B<--grp-problems>
+
+Shows a summary of all of the problems (services that are red) for all Host Groups
+defined in the L<spong.groups> file.
+
+=item B<--history> [I<hostlist>]
+
+Show history information for the the list of hosts in hostlist. If host
+list is not specified, all hosts defined in spong.hosts are displayed.
+
+=item B<--host> I<host>
+
+Shows all information available for the given host.
+
+=item B<--services> I<host>
+
+Shows detailed service information for the given host.
+
+
+=item B<--stats> I<host>
+
+Show statistical information for the given host.
+
+=item B<--config> I<host>
+
+Shows configuration information for the given host.
+
+=item B<--info> I<host>
+
+Shows admin supplied text for the given host.
+
+=item B<--service> I<host:service>
+
+Shows detailed information for the given host/service.
+
+=item B<--brief>
+
+Display output in a brief format.
+
+=item B<--standard>
+
+Display output in standard format (the default).
+
+=item B<--full>
+
+Display the maximum amount of information possible.
+
+=back
+
+=head1 CONFIGURATION
+
+=head2 Configuration Files
+
+By default the L<spong.conf> file is read on startup. It defines some specific
+variable that you probably don't need to override.
+
+After reading the configuration file, then reads the
+F<spong.conf.[host]> file where [host] is the host name of the machine that you
+are running on. Since these configuration files are just standard perl code
+that gets imported, the variables that you define in the host specific config
+file will take precedence over the standard configuration settings.
+
+=head2 Configuration Variables
+
+Here are a list of variables in the spong.conf file that are applicable
+to the spong-server program:
+
+=over
+
+=item $SPONGSERVER
+
+The make of the server that spong-server is running on.
+
+=item $SPONG_QUERY_PORT
+
+The port number that spong-server listens at for database queries.
+
+=back
+
+=head1 FILES
+
+=over
+
+=item spong.conf
+
+Configuration file. This contains variables that detail spong and OS specific
+definitions used by spong-server.
+
+=back
+
+=head1 DEPENDENCIES
+
+Perl v5.005_03 or greater is required.
+
+=head1 BUGS
+
+The B<--stats>, B<--config>, and B<--info> parameters are currently
+not implemented in the spong-server. When specified they will just generate
+a blank HTML page.
+
+=head1 SEE ALSO
+
+L<spong.hosts>, L<spong.conf>, L<user-guide>
+
+ http://spong.sourceforge.net/ the Spong Home Page
+
+=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 development until
+version 2.1. Stephen L Johnson took over development in October, 1999 with his
+changes which became Spong 2.5.
+
+L<check_snmp>
projects / spong.git / commitdiff