Provided by: spong-client_2.7.7-12_all bug

NAME

       spong-client - report system information to spong server

SYNOPSIS

       spong-client [ --debug-d n ] [ --kill--restart--nosleep--norefresh
       ] config-file

DESCRIPTION

       This program is run on each Unix machine in which you want to monitor
       local system attributes, and reports 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.

       Format of update messages

       It sends a message for each check to the spong server and reports the
       following:

       * hostname (where is this report coming from)
       * service name ("disk", "cpu", "procs", "logs", "local")
       * color ("red", "yellow", "green")
       * a one line summary
       * a more detailed message providing additional detail.

       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.

       Running the program

       You should start this program in your system startup file, and it
       should be running constantly. If no parameters are specified, spong-
       client forks and detaches itself to run as a daemon.

       If you provide the --debug n flag, then debugging information will be
       printed to stdout, otherwise output will only be produced if there is a
       problem. Where n is a number from 1 - 9. A higher number means more
       verbosity in the debugging output.

       If you provide the --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 --kill flag, a signal will
       be sent to the running spong-client process causing it to exit.

       The --nosleep or --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 (depreciated), this reduces the effectiveness of
       the check_logs module.

       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 $CHECKS
       configuration variable. Upon initialization, spong-client will load the
       modules defined in $CHECKS from the LIBDIR/Spong/Client/plugins/
       directory. As each module is initialized, it registers itself with the
       the plugins registry (see the Developer Guide).

       Extending Functionality

       Depreciated, please refer to "CLIENT MODULES" in developer-guide.

       If you want to check some service which is not being checked by
       spong-client, then you can define a "&check_local()" function in your
       config file (either in your standard spong.conf config file or your
       host specific spong.conf.hostname file - but not both!). That function
       can do anything you want, but at the end needs to call the "&status()"
       function to report what you have found to the spong server.

CONFIGURATION

       Configuration Files

       By default this reads the 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 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.

       Configuration Variables

       Here is a listing of the configuration variables applicable to the
       spong-client program.

       $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

       $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 $SPONGSLEEP{DEFAULT} value. If no value
           is then found, spong-client fall back to using $SPONGSLEEP.

       $SPONGTMP
           The directory that Spong programs use for temporary store and work
           files. It should be a different directory than /tmp for operation
           and security reasons.

       $SPONG_LOG_FILE
           If set to 1, spong-client will log errors to a log file in
           $SPONGTMP named spong-client.log.

       $SPONG_LOG_SYSLOG
           If set to 1, spong-client will log errors to the syslog using the
           USER facility and the ERR priority.

       $CHECKS
           A string that has the list of client check modules to run. If
           $CHECKS is missed or blank, spong-client defaults to "disk cpu
           processes logs".  If the "check_local()" function is present then
           ’local’ is appended.

       $CPUWARN, $CPUCRIT
           A number indicating the CPU load that triggers a problem ($CPUWARN
           triggers warnings - yellow, and $CPUCRIT triggers alerts - red).

       @PROCSWARN, @PROCSCRIT
           A list of processes that should be running, if they are not
           running, then trigger a problem (processes in @PROCSWARN trigger a
           warning - yellow, and processes in @PROCSCRIT trigger an alert -
           red).

       $LOGCHECKS
           A list of hashes which defined checks to apply to log files. Each
           hash contains the fields:

           logfile
               which is the full path to the log file to check

           checks
               a list of check to apply to the log file.

           Each check is a hash that contains the fields:

           pattern
               a Perl regular expression to be scanned for

           status
               the status color to reporte when lines match pattern

           duration
               the duration (in seconds) that each event is to be reported to
               the server

           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 pattern)

           id  an optional key field to associated with each event generated.
               The default key is the evaluated 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.

       $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.

FILES

       spong.conf, spong.conf.[hostname]

EXAMPLES

               spong-client --debug 5 --nosleep
               spong-client --debug 5
               spong-client --restart

DEPENDENCIES

       Perl v5.005_03 or greater is required.

BUGS

       No known bugs.

SEE ALSO

       spong-server, spong.conf, client-modules, developer-guide

AUTHOR

       Ed Hill <ed-hill@uiowa.edu>, Unix System Administrator, The University
       of Iowa

       Stephen L Johnson <sjohnson@monsters.org>

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.