NAME

spong.conf - provides configuration information to spong programs.


DESCRIPTION

The spong.conf file defines variables that are used by all pieces of spong. This file (and if it exists, a host specific spong.conf.<hostname> file) gets imported by each of the spong programs. It sets variables representing the following information:
    * Standard package information (servername, port number, file locations)


    * Service thresholds (how much load is ok, disk space, etc.)


    * OS specific variables (what df command/options should I use, etc.)
Depreciated: The spong.conf file can also contain a &check_local() function that will be run by the spong-client program to monitor some system specific service that is not done normally by the spong-client program. See the spong-client manpage for more details.

The 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 correct in Perl (which some would say is anything 8-).


STANDARD VARIABLES

$SPONGSLEEP
The amount of time (in seconds) to sleep before checking a service again (in the spong-network and spong-client programs). This is also the amount of time that the spong-display program sets to automatically refresh the web page. If the spong-server has not gotten an updated from a service in 2* $SPONGSLEEP , it considers that data to be ``old'', and sets the color of that service to purple.

 
$SPONGSERVER
The host that at least the spong-server, spong-display, and spong-message programs are running on. Typically the spong-network program runs on that host as well.

 
$SPONGPORT
The port that the spong-server is listening at.

 
$SPONGTMP
A temporary directory where output from some commands are kept for short periods of time. For security reasons, this should probably be something other then /tmp, or /var/tmp.

 
$SPONGDB
The directory on the spong server machine where status report and all other infomation for each host is kept. Each category of information has it's own subdirectory (i.e. status - services status information, history - history files, info - addition information to be displayed on service displays, etc.)

 
$SPONG_UPDATE_PORT
The port that the spong-server listens at for status updates from clients.
$SPONG_QUERY_PORT
The port that the spong-server listens at for database queries. This is the port that the CGI and command line interface programs use.
$SPONG_BB_UPDATE_PORT
The port the the spong-server listens at for Big Brother client status updates. This spong-server only provides partial Big Brother emulation at present. It will only understand status updates,
$SPONG_SERVER_ALARM
This is the maximum amount of time (in seconds) that Spong Client can stay connected to the Spong Server status update ports. Set the value to '0' to disable the timeout.
$WWW_USE_IMAGES
That is a flag to indicate whether you want to use graphic dots for the status displays on the web display or use colored text areas. Soem browsers seem to have performance problems when display a full windows of the graphic dots. If your browsers are having problems, change this value to 0.
$WWWGIFS
This is the path portion of the URL to where the graphics dot images reside.
%WWW_COLOR
This hash contains the HTML color codes to be used for the various status colors when WWW_USE_IMAGES is 0. There should be entries for "red", "yellow", "green", "blue" and "purple".
$WWWHTML
The full file path to where the '/html' directory of the Spong WWW data was installed. It should be the $IWWW directory specified in the build  installation program plus "/html' (i.e. $IWWW/html). This directory is the repository of the online help documentation. You can also specifiy customize html headers and footer on the web pages generated (see the Administrators Guide).
$WWWSPONG
The full URL to access the www-spong CGI program. This URL is used by www-spong while generate web pages to provide links to move deeper web pages.
$WWWACK
The full URL to access the www-spong-ack CGI program. This URL is used by www-spong to generate links which allow Spong Acknowledgements to be generated.
$WWWCONTACT
The full URL to a customized CGI program that provide a way of contacting staff. www-spong will generate "smart" links depending on the web page being displayed. for more information on this feature, please see the Administrator Guide.
$WWW_ACTIONBAR_CUSTOM
This parameter can be used to customize the Host/Service displays Action Bar of the Web Interface. Any HTML code in this parameter will be included on the Web Pages when they are displayed. This parameter is preprocessed by eval'ed before the contents is printed. Your can include complex perl variables and simple Perl code in this parameter. NOTE: Use single quoted to enclose the parameter contents to prevent premature expansion of any perl variables defined.
@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 any of these variables, www-spong will attach a REFRESH meta tag to reload the web pages every $SPONGSLEEP seconds. See the Administrator Guide for more details.
@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 any of these variables, 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 Administrator Guide for more details.

 

SPONG CLEANUP VARIABLES
$SPONG_ARCHIVE
The directory where to put old history file entries for each host. Each host have it's own file in this directory
$OLD_HISTORY
This is the number of days of history to keep for each host in the spong-server database. Any old history is append to the file for the host under the $SPONG_ARCHIVE directory.
$OLD_SERVICE
This is the number of days to retain stale service status (i.e. purple status) entries in the spong-server database. Any service service status entries older than $OLD_SERVICE days old are deleted from the database.

SERVICE THRESHOLD VARIABLES

@DFIGNORE
A list of regular expression strings that are matched against the raw file system names. If matched, then that file system is ignored. For example, having ``:'' in this list will cause NFS file system mounts to be ignored.

 
%DFWARN, %DFCRIT
 A hash of file systems (or the word ``ALL''), and the percentage that should trigger a problem (%DFWARN triggers warnings - yellow, and %DFCRIT triggers alerts - red). If a file system is not explicitly listed in this hash then it will fall back to the value of the ``ALL'' entry.

 
$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 and checks whch  is 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 reported lines matching pattern, duration - the duration that each event is to be reported to the server, text - the text to reported back in the detailed message field of the status report (which can include match position variables from pattern) and id - an optional key field to associated with each event generated.  See the check_logs documentation for more information and examples.

 
%HTTPDOCS, %HTTPPORT
These variables provide some parameters when checking http based servers. The %HTTPDOCS variable is keyed by host (or the string ``ALL'' for all hosts), and contains as a value, a list of documents to check on that host. The default setting is to search for the ``/robots.txt'' file on all hosts.
The %HTTPPORT variable contains the port number that web server on a given host is running on. By default the value is 80, but this can be overridden on a host by host basis

 
$SEND_MESSAGE
$SEND_MESSAGE defines when spong-message is called by spong-server. This variable can contain one of four valid values. If it is ``RED'', then spong-message is called for every time a system or service reports a problem. If its value is ``CHANGE'', then spong-message is only called when there is a change of state . If this values is "RED-CHANGE", then spong-message is called  everytime 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 spong-message is never called.

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

 
$IDENT_MESSAGES_PER_HOUR
This is the maximum number of identical messages that are sent to the same person in an hour. The default value is 3.

OS SPECIFIC VARIABLES

$DF, $UPTIME, $PS, $GREP, $PING, $TRACEROUTE, $MAILQ
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.

FUNCTIONS

DEPRECIATED:  spong-client checks are now modules. See Client Modules in the Developer Guide documentation.
 

You can defined a &check_local() function in the spong.conf file that will be run by the spong-client program. This function can be used to extend the functionality of spong-client, and allow you to check on some service beyond the four (disk, cpu, procs, logs) that spong-client already checks.

Here is an example &check_local() function that we run on some of our machines to check to make sure that our sendmail mail queue is not getting too large.

 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, "" );
 }

FILES

/usr/local/etc/spong/spong.conf
This is the standard spong.conf file that is read by all spong programs.

 
/usr/local/etc/spong/spong.conf.[host]
This is a spong.conf file that if it exists on a given host, it will be 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 first, and then if it can not find it - it looks for the shorter name.

SEE ALSO

the perl manpage , the spong-server manpage , the spong-network manpage , the spong-client manpage , the spong-display manpage , the spong-message manpage , spong.hosts


AUTHOR

Ed Hill (ed-hill@uiowa.edu), Unix System Administrator, The University of Iowa
Stephen L Johnson (stephen.johnson@mail.state.ar.us) or (sjohnson@monsters.org), Unix System Administator, DIS - State of Arkansas

Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong).