--- /dev/null
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <meta name="GENERATOR" content="Mozilla/4.61 [en] (X11; U; Linux 2.2.12-20 i686) [Netscape]">
+ <title>spong-client</title>
+</head>
+<body>
+<b><font face="Arial, Helvetica, sans-serif"><font size=+2>Name</font></font></b>
+<p><b>spong-client</b> - report system information to spong server.
+<p><b><font face="Arial, Helvetica, sans-serif"><font size=+2>SYNOPSIS</font></font></b>
+<p><b>spong-client</b> [--debug] [--kill|--restart|--nosleep|--refresh]
+[config_file]
+<p><b><font face="Arial, Helvetica, sans-serif"><font size=+2>DESCRIPTION</font></font></b>
+<p>This program is run on each Unix (and NT) 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<b>% </b>of the total you have specified, to keep clients from syncing
+up and overloading the spong-server).
+<p>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.
+<p>It sends a message for each check to the spong server and reports the
+following:
+<ul>
+<li>
+hostname (where is this report coming from)</li>
+
+<li>
+service name ("disk", "cpu", "procs", "logs", "local")</li>
+
+<li>
+color ("red", "yellow", "green")</li>
+
+<li>
+a one line summary</li>
+
+<li>
+a more detailed message providing additional detail.</li>
+</ul>
+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.
+<p>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).
+<p>The more detailed message contains information such as the complete
+df output, or a listing of the top 10 processes sorted by CPU.
+<p>You should start this program in your system startup file, and it should
+be running constantly. If you provide the --debug flag, then debugging
+information will be printed to stdout, otherwise output will only be produced
+if there is a problem.
+<p>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 flags
+causs the program to cycle through all of the checks one and hen exit.
+These flags can be used to run spong-client as a cron job (<b>depreciated</b>,
+this reduced the effectivemess of the check_logs module, see: <a href="check_logs.html">Client
+Modules</a>).
+<p><b><font face="Arial, Helvetica, sans-serif"><font size=+2>CONFIGURATION</font></font></b>
+<p>By default this reads the <a href="spong-client.html#spong-client_usr_local_etc_spong_spong_conf_0">/usr/local/etc/spong/spong.conf</a>
+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.
+<p>After reading the configuration file that you specify (or the default),
+it then reads the <i>/usr/local/etc/spong/spong.conf.[host]</i> file where
+[host] 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.
+<p>Here is a listing of the configuration variables applicable to the spong-client
+program.
+<blockquote><b>$SPONGSLEEP</b>, <b>$SPONGSERVER</b>, <b>$SPONGPORT</b>
+<br>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
+on.
+<p><b>$CHECKS</b>
+<br>A string that has the list of client check modules to run. If $CHECK
+is missed or blank, spong-client defaults to "disk cpu processes logs".
+If the <i><tt>&check_local()</tt> </i>function is present then 'local'
+is appened.
+<br>
+<p><b>$CPUWARN</b>, <b>$CPUCRIT</b>
+<br>A number indicating the CPU load that triggers a problem (<b>$CPUWARN</b>
+triggers warnings - yellow, and <b>$CPUCRIT</b> triggers alerts - red).
+<p><b>@PROCSWARN</b>, <b>@PROCSCRIT</b>
+<br>A list of processes that should be running, if they are not running,
+then trigger a problem (processes in <b>@PROCSWARN</b> trigger a warning
+- yellow, and processes in <b>@PROCSCRIT</b> trigger an alert - red).
+<p><b>$LOGCHECKS</b>
+<br>A list of hashes which defined checks to apply to log files. Each hash
+contains the fields <b>logfile</b> which is the full path to the log file
+to check and <b>checks</b> whch is a list of check to apply to the
+log file. Each check is a hash that contains the fields: <b>pattern</b>
+- a Perl regular expression to be scanned for, <b>status</b> - the status
+color to reported lines matching pattern, duration - the duration that
+each event is to be reported to the server, <b>text </b>- the text to reported
+back in the detailed message field of the status report (which can include
+match position variables from <b>pattern</b>) and <b>id</b> - an optional
+key field to associated with each event generated.
+<p><b>$DF</b>, <b>$UPTIME</b>, <b>$PS</b>, <b>$GREP</b>
+<br>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.
+<br> </blockquote>
+<b><font face="Arial, Helvetica, sans-serif"><font size=+2>CLIENT CHECKS</font></font></b>
+<p><font face="Arial, Helvetica, sans-serif"> </font>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 <b>$CHECKS</b> configuration
+variable. Upon initialization, <i>spong-client </i>will load the modules
+defined in <b>$CHECKS </b>from the <i>"LIBDIR/Spong/Client/plugins/"</i>
+directory. As each modules is initialized, it registers itself with the
+the plugins registery (see the <a href="developer-guild.html">Developer
+Guide</a>). Spong comes with a standard set of clients <i>check_disk</i>,
+<i>check_cpu</i>,
+<i>check_processes</i>
+and <i>check_logs </i>(see <a href="client-modules.html">Client Modules</a>
+for details.)
+<p><b><font face="Arial, Helvetica, sans-serif"><font size=+2>EXTENDING
+FUNCTIONALITY</font></font></b>
+<p><b>Depreciated,</b> please refer to the <a href="developer-guide.html#developer.guide.client_modules">Client
+Modules</a> section of the <a href="developer-guild.html">developer guide</a>.
+<p>If you want to check some service which is not being checked by spong-client,
+then you can define a <tt>&<i>check_local()</i></tt> function in your
+config file (either in your standard config file or your host specific
+file - but not both!). That function can do anything you want, but at the
+end needs to call the <tt>&<i>status()</i></tt> function to report
+what you have found to the spong server.
+<pre> &status( SERVERADDR, HOST, SERVICE, COLOR, SUMMARY, MESSAGE )</pre>
+The arguments to the <tt>&<i>status()</i></tt> function are:
+<pre> * SERVERADDR - Should be $SPONGSERVER
+ * HOST - The full hostname of the machine you are on
+ * SERVICE - Should be the string local.
+ * COLOR - Either "red", "yellow", or "green"
+ * SUMMARY - A short one line summary of the status
+ * MESSAGE - More detailed information (can be multi-lined)</pre>
+Here is an example <tt>&<i>check_local()</i></tt> function that we
+run on some of our machines to check to make sure that our sendmail mail
+queue is not getting too large.
+<pre>sub check_local {
+ my $color = "green";
+ my $summary = "";
+ my $rt = `mailq | head -1`;
+
+ chomp $rt;
+ if( $rt =~ /\((\d+) request/ ) {
+ $items = $1
+ if( $items > 1000 ) {
+ $color = "red";
+ } elsif( $items > 500 ) {
+ $color = "yellow";
+ }
+
+ $summary = "$items messages in the mail queue";
+ } else {
+ $color = "yellow";
+ $summary = "Can't parse mailq output: $rt";
+ }
+
+ &status( $SPONGDISPLAY, $HOST, "local", $color, $summary, "" );
+}</pre>
+<b><font size=+2>FILES</font></b>
+<dl>
+<dt>
+<b>/usr/local/etc/spong/spong.conf</b></dt>
+
+<dd>
+Configuration file. This contains variables that detail spong and OS specific
+definitions used by spong-client. This file also contain variables describing
+threshold levels. See <i>spong.conf</i> for additional documentation.</dd>
+</dl>
+<b><font face="Arial, Helvetica, sans-serif"><font size=+2>DEPENDENCIES</font></font></b>
+<p>Perl v5.003 or greater is required.
+<p><b><font face="Arial, Helvetica, sans-serif"><font size=+2>BUGS</font></font></b>
+<p>None know bugs.
+<p><b><font face="Arial, Helvetica, sans-serif"><font size=+2>SEE ALSO</font></font></b>
+<p>the <i>spong-server</i> manpage , <i>spong.conf, client-modules, develper-guild</i>
+<p><b><font face="Arial, Helvetica, sans-serif"><font size=+2>AUTHOR</font></font></b>
+<p>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>
projects / spong.git / commitdiff