From: Stephen L Johnson Date: Fri, 26 May 2000 19:25:57 +0000 (+0000) Subject: added into repository X-Git-Tag: spong-2_7-alpha7~21 X-Git-Url: http://git.etc.gen.nz/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4715be28225257546a6935b873f7ae47214d6be0;p=spong.git added into repository --- diff --git a/pod/spong.conf.pod b/pod/spong.conf.pod new file mode 100644 index 0000000..dea60ab --- /dev/null +++ b/pod/spong.conf.pod @@ -0,0 +1,370 @@ +=head1 NAME + +B - provides configuration information to spong programs. + +=head1 DESCRIPTION + +The F file defines variables that are used by all pieces of spong. +This file ( and if it exists FhostnameE> file ) gets +imported by each of the spong programs + +The variables are grouped by the spong programs. Each section will list the +varirables that are used in the program along with the meaning of the +variable to the program. + +=head2 All programs + +This sections deals with varirables that are used by all of the spongs +programs. Any differences in how the programs use the variable will be detailed in the I<"Configuration Variables"> section of the program's documentation. + +=over + +=item $SPONGSLEEP (Depreciated) + +This variable holds the amount in time in seconds) that spong client programs +(i.e. B and B) are expected to sleep between +checking cycles. For B this is the time to live for statuses. If +a tatus has not been updated in 2 * $SPONGSLEEP seconds it is considered to be +old and the color is set to 'purple'. For www-spong, $SPONGSLEEP represents the +amount of time to automatically refresh the web page. + +=item $SPONGSLEEP{'DEFAULT'}, $SPONGSLEEP{'Eprogram-nameE'} + +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 +I<$SPONGSLEEP{'DEFAULT'}> value. If no value is then found, the spong program +will fall back to using $SPONGSLEEP. + +=item $SPONGSERVER + +The host that at least the L and L +programs are running on. Typically the L program runs on that +host as well. + +=item $SPONG_UPDATE_PORT + +This variable defines the port that the L update process listens +on. If this variable is not defined on the I<$SPONGSERVER> host, the +L update process will not be started. The default value is 1998. + +=item $SPONG_QUERY_PORT + +This varirable defines the port that the L query process listens +on. If this varirable is not defined on the I<$SPONGSERVER> host, the +L query process will not be started. The default value is 1999. + +=item $SPONG_BB_UPDATE_PORT + +This variable defines the port that the Big Brother BBSERVER emulation process +listens on. If this variable is not defined on the I<$SPONGSERVER> host, the +Big Brother BBSERVER emluation process will not be started. The default value +is 1984. + +=item $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 F, or F. + +=item $SPONG_LOG_FILE + +If set to I<1>, B will log errors to a log file in I<$SPONGTMP> +named F. + +=item $SPONG_LOG_SYSLOG + +If set to I<1>, B will log errors to the syslog using the +I facility and the I priority. + +=back + +=head2 spong-server + +=over + +=item $SPONGDB + +This defines the directory where the Spong database will be stored. Each host +will have a subdirectory in this directory which is named for the host. + +=item $SPONGSTATUS + +If this variable is set to 1, it will enable the storing of the update +status message information for each event that is generated in the history +log. This status message information is access via the web interface by +click on the status color or icon link of an event in a History Listing. + +=item $SPONG_SERVER_ALARM + +This variable defined the maximum amount of time (in seconds) that a incoming +connection of a status message can last. Once the time limit is exceeded +B will terminated the connection. This action can be disables +by setting the variable to zero (0). + +=item $WWW_FQDN + +Set this variable to 1 to display the fully qualified domain name (FQDN) of +hosts in Spong client displays. Otherwise only the first element of the FQDN +will be displayed. + +=item $SEND_MESSAGE + +I<$SEND_MESSAGE> defines when B is called by B. +This variable can contain one of four valid values. If it is ``RED'', then +B is called for every time a system or service reports a +problem. If its value is ``CHANGE'', then B is only called when +there is a change of state . If this values is ``RED-CHANGE'', then +B 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 +B is never called. + +=back + +=head2 www-spong + +=over + +=item $WWWGIFS + +This L<$WWW_USE_IMAGES> is set to 1, this variable should be set to the +URL path of the F directory with the document tree of the web +server. + +=item $WWWHTML + +This should be the full path name to the F directory of your +Spong installation. + +=item $WWWSPONG + +This should be the URL path to the location of the L CGI program +with your web server's document tree. + +=item $WWW_ACTIONBAR_CUSTOM + +The variable defined HTML code that will be appended to the Action Bar at +the top of Host Displays in the right frame of the web client interface. This +code is eval'ed before display. You can include perl code and variables. The +perl varirable C<$name> holds the FQDN of the host being displayed. + +=item $WWW_PROB_ACTIONBAR + +This variable is similar in function to the $WWW_ACTIONBAR_CUSTOM varirable. +Except this action bar is display after each host listed in the problem +frame (left) of the client web interface. + +=item $WWW_TITLE_ACTIONBAR + +This varirable can host HTML code that will be appended to the action bar +that is display in the title (top) frame of the client web display. This +code is eval'ed before display. You can include perl code and variables. This +action bar is only displays if L<$WWWFRAMES> is set to 3. + +=item $WWW_TITLE_COLOR + +Defines the background color for table title cells in the client web inerface. +The colors are defined in the HTML color format. + +=item $WWW_CELL_COLOR + +This varirable defined the background color for normal table cells in the +client web interface. The colors are definedin the HTML color format. + +=item $WWW_COLOR{...} + +This perl hash contains the HTML color codes for the various Spong status +colors. The can tweak the colors to your own preferences. It is strongly +suggested that you don't move the colors outside of their color family, +unless you throughly document your changes. + +=item $WWWFRAMES + +This determined the type of frame interface that is used in the web interface +client of L. The variable can be set to 2 or 3. The default value is +2. See L for more information. + +=item @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 L will attach a REFRESH meta tag to reload +the web pages every L<$SPONGSLEEP> seconds. See the L for more details. + +=item @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, L 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 L for more +details. + +=back + +=head2 www-spong-ack + +=over + +=item $WWWSPONGACK + +This should be the URL path to the location of the L CGI program +with your web server's document tree. + +=back + +=head2 spong-cleanup + +=over + +=item $SPONG_ARCHIVE + +The directory where to put old history file entries for each host. Each host +has it's own file in this directory. + +=item $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 I<$SPONG_ARCHIVE> directory. + +=item $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. + +=back + +=head2 spong-client + +=over + +=back + +=item @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. + +=item %DFWARN, %DFCRIT + +A hash of file systems (or the word ``ALL''), and the percentage +that should trigger a problem (I<%DFWARN> triggers warnings - yellow, +and I<%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. + +=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 I which is the full path to the log file +to check and I which is a list of check to apply to the +log file. Each check is a hash that contains the fields: I +- a Perl regular expression to be scanned for, I - the status +color to reported lines matching pattern, duration - the duration that +each event is to be reported to the server, I- the text to reported +back in the detailed message field of the status report (which can include +match position variables from I) and I - an optional +key field to associated with each event generated. See the L +documentation for more information and examples. + +=item %HTTPDOCS, %HTTPPORT + +These variables provide some parameters when checking http based servers. The +I<%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 I<%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. + +=head2 spong-message + +=over + +=item $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. + +=item $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. + +=back + +=head2 OS SPECIFIC VARIABLES + +These are various external programs that Spong uses to gather system +informationto evaluate in it's checks. It is I> recommended that you +use the full path names for the values of these varirables. + +=over + +=item $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. + +=back + + +=head1 FILES + +=over + +=item F + +This is the standard spong.conf file that is read by all spong programs. + +=item F + +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. + +=head1 SEE ALSO + +L , L, L, , L, L, +L, 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 development until +version 2.1. Stephen L Johnson took over development in October, 1999 with his +changes which became Spong 2.5. + diff --git a/pod/spongfaq.pod b/pod/spongfaq.pod new file mode 100755 index 0000000..6237593 --- /dev/null +++ b/pod/spongfaq.pod @@ -0,0 +1,142 @@ +=head1 NAME + +spongfaq - frequently asked questions about Spong ($Revision: 1.1 $, $Date: 2000/05/26 19:25:57 $) + +=head1 DESCRIPTION + +This document contains a list of the most Frequently Asked Questions +(FAQ) about Spong. It is really not a HOWTO, but is in a classical Question +/ Answer form. + +=head2 1. What is Spong? + +This is hopefully a B tool. It does not compete with Tivoli, OpenView, +UniCenter, or any other commercial packages, and I have no intention of +trying to turn it into one. It is not SNMP based, it communicates via simple +TCP based messages. It is written in Perl, so hopefully it can be run on +multiple systems + +It has the following features: + +=over 4 + +=item * client based monitoring (CPU, disk, processes, logs, etc...) + +=item * monitoring of network services (smtp, http, ping, pop, dns, etc...) + +=item * grouping of hosts (routers, servers, workstations, PCs) + +=item * rules based messaging when problems occur + +=item * configurable on a host by host basis + +=item * results displayed via text or web based interface + +=item * history of problems + +=item * verbose information to help diagnosis problems + +=back + + +=head2 2. Why doesn't my spong-client status update show up? + +If your spong-client is setup and runs properly (i.e. spong-client --debug +shows that the checks are being run and the results are being sent to the +spong-server). Depending on how your server is setup, the full domain name of +your host may not returned with the code that spong-client uses. + +The spong-server has a bit of security for status update messages. The +host name in the status message must match a host name defined in the spong.hosts +files. spong-client uses the gethostbyname() function to try to resolve +the host's full name. If it just gets the host name without the domain, +spong-server will quietly reject and drop the message. + + +You can run the perl snippet below to determine what host name that +spong-client is resolving for the machine it is running on. + + perl -MSys::Hostname -e \ + '($h) = (gethostbyname(Sys::Hostname::hostname()))[0]; print "$h\n"' + +It should print out you the fully qualified domain name of your system. +This should match the hostname configured in the song.hosts file on the +spong-server macine. If they don't match then you can do 1 of 2 things. + + +In your hosts file make use that the full domain name is the first name +of your host's line. i.e. + + 192.168.2.34 my-host.inkcom.com my-host + + +Or put if your system is in your DNS server properly, make sure that 'dns' is +in front of 'file' on the hosts: line of the /etc/nsswitch.conf file. + +There a utility L in the F directory of +the Spong distribution. You can run it on a machine to make sure that it +is setup correctly to resolve it's full quality domain name. The utility +is run by enter the following command C. + +=head2 3. How do I get e-mail/paging/alpha paging/notifications to work? + +The most important thing is to go through the L, L, +and L configuration files. And be sure to read the documention +for L, L L, configuration files and the +L and L programs. + +If you are still having problems, follow the check list below to help +resolve your problem. + +=item 1. $SEND_MESSAGE in spong.conf + +In spong.conf make sure the $SEND_MESSAGE is set to 'RED', 'CHANGE' or +'RED-CHANGE'. + +=item 1. $RULES_MATCH in spong.conf + +In spong.message make sure that $RULES_MATCH is set to 'ALL' or +'FIRST-MATCH'. If you set it to 'OLD', spong-message will revert to the old +notification method in Spong 2.0 - 2.1. + +=item 1. Messaging rules in spong.message + +If your are having problems with defining your rules, put in a very +minimal rules set. + + $MESSAGING_RULES = [ + { + contacts => [ 'sjohnson' ] + }, + ]; + +This will send everything to the 'sjohnson' contact. + +=item 1. %HUMANS in spong.hosts + +In spong.hosts, you must define at least one contact (the %HUMANS in spong.hosts) +in order to have any notifications sent. for the example rule setup above, +to get e-mail sent to that user you can have an entry like: + + %HUMANS = ( + 'sjohnson' => { + name => 'Stephen Johnson', + email => 'stephen.johnson@mailhost.at.my.com', + }, + ); + +=item 1. Testing messaging rules + +You can test your $MESSAGING_RULES defined in spong.message by running +spong-message in debugging mode to see what is happening step by step: + + spong-message --debug red hostname.my.com disk 98765432 'This is a test' + +This will generate a lot of verbose output. You might want to redirect +it to a file. spong-message counts rules starting with 0 just to be forewarned. + +=back + +=head1 AUTHORSHIP and COPYRIGHT + +Copyright (c) 1999-2000 Stephen L Johnson