--- /dev/null
+=head1 NAME
+
+B<spong.conf> - provides configuration information to spong programs.
+
+=head1 DESCRIPTION
+
+The F<spong.conf> file defines variables that are used by all pieces of spong.
+This file ( and if it exists F<spong.conf.E<lt>hostnameE<gt>> 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<spong-client> and B<spong-network>) are expected to sleep between
+checking cycles. For B<spong-server> 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{'E<lt>program-nameE<gt>'}
+
+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<spong-server> and L<spong-message>
+programs are running on. Typically the L<spong-network> program runs on that
+host as well.
+
+=item $SPONG_UPDATE_PORT
+
+This variable defines the port that the L<spong-server> update process listens
+on. If this variable is not defined on the I<$SPONGSERVER> host, the
+L<spong-server> update process will not be started. The default value is 1998.
+
+=item $SPONG_QUERY_PORT
+
+This varirable defines the port that the L<spong-server> query process listens
+on. If this varirable is not defined on the I<$SPONGSERVER> host, the
+L<spong-server> 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</tmp>, or F</var/tmp>.
+
+=item $SPONG_LOG_FILE
+
+If set to I<1>, B<spong-network> will log errors to a log file in I<$SPONGTMP>
+named F<spong-network.log>.
+
+=item $SPONG_LOG_SYSLOG
+
+If set to I<1>, B<spong-network> will log errors to the syslog using the
+I<USER> facility and the I<ERR> 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<spong-server> 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<spong-message> is called by B<spong-server>.
+This variable can contain one of four valid values. If it is ``RED'', then
+B<spong-message> is called for every time a system or service reports a
+problem. If its value is ``CHANGE'', then B<spong-message> is only called when
+there is a change of state . If this values is ``RED-CHANGE'', then
+B<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
+B<spong-message> 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<www/gifs> directory with the document tree of the web
+server.
+
+=item $WWWHTML
+
+This should be the full path name to the F<www/html> directory of your
+Spong installation.
+
+=item $WWWSPONG
+
+This should be the URL path to the location of the L<www-spong> 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<www-spong>. The variable can be set to 2 or 3. The default value is
+2. See L<user-guide> 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<www-spong> will attach a REFRESH meta tag to reload
+the web pages every L<$SPONGSLEEP> seconds. See the L<Administrator
+Guide|admin-guide/"Autorefresh"> 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<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 L<Administrator Guide|admin-guide/"Autorefresh"> for more
+details.
+
+=back
+
+=head2 www-spong-ack
+
+=over
+
+=item $WWWSPONGACK
+
+This should be the URL path to the location of the L<www-spong-ack> 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<logfile> which is the full path to the log file
+to check and I<checks> which is a list of check to apply to the
+log file. Each check is a hash that contains the fields: I<pattern>
+- a Perl regular expression to be scanned for, I<status> - the status
+color to reported lines matching pattern, duration - the duration that
+each event is to be reported to the server, I<text>- the text to reported
+back in the detailed message field of the status report (which can include
+match position variables from I<pattern>) and I<id> - an optional
+key field to associated with each event generated. See the L<check_logs>
+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<strongly>> 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<SPONGHOME/etc/spong.conf>
+
+This is the standard spong.conf file that is read by all spong programs.
+
+=item F<SPONGHOME/etc/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.
+
+=head1 SEE ALSO
+
+L<perl> , L<spong-server>, L<spong-network>, , L<spong-client>, L<www-spong>,
+L<www-spong-ack>, L<spong-cleanup>, L<spong-message>
+
+=head1 AUTHOR
+
+Ed Hill <F<ed-hill@uiowa.edu>>, Unix System Administrator, The University of
+Iowa
+
+Stephen L Johnson <F<sjohnson@monsters.org>>
+
+=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.
+
--- /dev/null
+=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<simple> 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</li>
+
+=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<gethost-test> in the F</utils/> 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<perl gethost-test>.
+
+=head2 3. How do I get e-mail/paging/alpha paging/notifications to work?
+
+The most important thing is to go through the L<spong.conf>, L<spong.hosts>,
+and L<spong.message> configuration files. And be sure to read the documention
+for L<spong.conf>, L<spong.hosts> L<spong.message>, configuration files and the
+L<spong-message> and L<spong-server> 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
projects / spong.git / commitdiff