From: Stephen L Johnson Date: Wed, 10 May 2000 04:15:22 +0000 (+0000) Subject: updated inline documentation in pod format added X-Git-Tag: spong-2_7-alpha7~27 X-Git-Url: http://git.etc.gen.nz/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1c36fb6fdc37f6978da70e1c045a6a4953c76c04;p=spong.git updated inline documentation in pod format added --- diff --git a/src/spong-client.pl b/src/spong-client.pl index 3948174..8da94be 100755 --- a/src/spong-client.pl +++ b/src/spong-client.pl @@ -1,4 +1,26 @@ #!@@PERL@@ + +=head1 NAME + +spong-client - report system information to spong server + +=head1 SYNOPSIS + +B [ B<--debug>|B<-d> I ] +[ B<--kill>|B<--restart>|B<--nosleep>|B<--norefresh> ] F + +=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 @@ -267,3 +289,220 @@ sub load_checks { 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 flag, then debugging +information will be printed to stdout, otherwise output will only be produced +if there is a problem. Where I 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), this reduced the effectiveness of the L +module. + +=head2 Configuration Files + +By default this reads the L 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 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 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 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) + +=item id + +an optional key field to associated with each event generated. The default +key is the evaluated I 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 will load the +modules defined in I<$CHECKS> from the F +directory. As each modules is initialized, it registers itself with the the +plugins registery (see the L. Spong comes with +a standard set of client checks, see L for +a more information. + +=head2 Extending Functionality + +B, please refer to the L 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 config file or your host specific L +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, F + +=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, F, F, L, +L + +=head1 AUTHOR + +Ed Hill >, Unix System Administrator, The University of Iowa + +Stephen L Johnson > + +=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.