#!@@PERL@@
+
+=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 1p% of the total you have specified, to keep clients from syncing
+up and overloading the spong-server).
+
+=cut
+
#
# Spong client monitoring script. This runs various tests locally on a machine
# and sends those results to the Spong server machine where the information
if ( $@ ) { &error( "Could not load $check check plugin" ); }
}
}
+
+__END__
+
+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
+
+=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
+df output, or a listing of the top 10 processes sorted by CPU.
+
+=head2 Running the program
+
+You should start this program in your system startup file, and it should be
+running constantly. If you provide the B<--debug> I<n> flag, then debugging
+information will be printed to stdout, otherwise output will only be produced
+if there is a problem. Where I<n> is a number from 1 - 9. A higher number means
+more verbosity in the debugging output.
+
+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 L<check_logs>
+module.
+
+=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 $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
+
+=head2 Client Checks
+
+The checks are actually a set of modules that are called in series by
+spong-client. The list of modules to run are defined in the I<$CHECKS>
+configuration variable. Upon initialization, B<spong-client> will load the
+modules defined in I<$CHECKS> from the F<LIBDIR/Spong/Client/plugins/>
+directory. As each modules is initialized, it registers itself with the the
+plugins registery (see the L<Developer Guide|developer-guide>. Spong comes with
+a standard set of client checks, see L<Client Modules|client-modules> for
+a more information.
+
+=head2 Extending Functionality
+
+B<Depreciated>, please refer to the L<Client Modules|developer-guide/"Client Modules"> section of the Developer Guide.
+
+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>
+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 FILES
+
+F</usr/local/etc/spong/spong.conf>, F</usr/local/etc/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>,
+L<client-modules>
+
+=head1 AUTHOR
+
+Ed Hill <F<ed-hill@uiowa.edu>>, Unix System Administrator, The University of Iowa
+
+Stephen L Johnson <F<sjohnson@monsters.org>>
+
+=head1 HISTORY
+
+Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong). Ed Hill
+original converted Big Brother (http://www.bb4.com) into Perl which diverged
+from Big Brother to become Spong. Ed Hill continued Spong develop until version
+2.1. Stephen L Johnson tool over development in October, 1999 with his changes
+which became Spong 2.5.
projects / spong.git / commitdiff