From: Stephen L Johnson Date: Mon, 22 Nov 1999 03:36:41 +0000 (+0000) Subject: Initial revision X-Git-Tag: spong-2_6-beta7~16 X-Git-Url: http://git.etc.gen.nz/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=52990990304a510f2999207cb9d47a62460465bf;p=spong.git Initial revision --- diff --git a/www/docs/spong_conf.html b/www/docs/spong_conf.html new file mode 100755 index 0000000..7a87b43 --- /dev/null +++ b/www/docs/spong_conf.html @@ -0,0 +1,401 @@ + + + + + + spong.conf + + + +

+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,
+$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_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.

+ +

+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). + +