From adc4241060f0b83d1b9d4ec202bf5db11da6e7be Mon Sep 17 00:00:00 2001 From: Jan Willamowius Date: Fri, 30 Sep 2005 07:47:25 +0000 Subject: [PATCH] add missing doc files from 2.7.7 release --- www/docs/admin-guide.html | 524 +++++++++++++++++++++++ www/docs/check_interfaces.html | 144 +++++++ www/docs/check_snmp.html | 136 ++++++ www/docs/data_sendmsg.html | 90 ++++ www/docs/developer-guide.html | 510 ++++++++++++++++++++++ www/docs/pre_redirect.html | 64 +++ www/docs/spong-ack.html | 172 ++++++++ www/docs/spong-cleanup.html | 133 ++++++ www/docs/spong-client-mod-template.html | 129 ++++++ www/docs/spong-client.html | 284 ++++++++++++ www/docs/spong-intro.html | 485 +++++++++++++++++++++ www/docs/spong-message-mod-template.html | 32 ++ www/docs/spong-message.html | 380 ++++++++++++++++ www/docs/spong-network-mod-template.html | 129 ++++++ www/docs/spong-network.html | 246 +++++++++++ www/docs/spong-server-mod-template.html | 291 +++++++++++++ www/docs/spong-server.html | 328 ++++++++++++++ www/docs/spong-status.html | 147 +++++++ www/docs/spong.conf.html | 429 +++++++++++++++++++ www/docs/spong.groups.html | 191 +++++++++ www/docs/spong.hosts.html | 306 +++++++++++++ www/docs/spong.html | 175 ++++++++ www/docs/spong.message.html | 443 +++++++++++++++++++ www/docs/spongfaq.html | 237 ++++++++++ www/docs/spongindex.html | 308 +++++++++++++ www/docs/spongtoc.html | 53 +++ www/docs/todo.html | 141 ++++++ www/docs/user-guide.html | 341 +++++++++++++++ www/docs/www-spong-ack.html | 129 ++++++ www/docs/www-spong.html | 206 +++++++++ 30 files changed, 7183 insertions(+) create mode 100755 www/docs/admin-guide.html create mode 100644 www/docs/check_interfaces.html create mode 100644 www/docs/check_snmp.html create mode 100644 www/docs/data_sendmsg.html create mode 100755 www/docs/developer-guide.html create mode 100644 www/docs/pre_redirect.html create mode 100644 www/docs/spong-ack.html create mode 100644 www/docs/spong-cleanup.html create mode 100755 www/docs/spong-client-mod-template.html create mode 100755 www/docs/spong-client.html create mode 100644 www/docs/spong-intro.html create mode 100755 www/docs/spong-message-mod-template.html create mode 100755 www/docs/spong-message.html create mode 100755 www/docs/spong-network-mod-template.html create mode 100755 www/docs/spong-network.html create mode 100755 www/docs/spong-server-mod-template.html create mode 100755 www/docs/spong-server.html create mode 100644 www/docs/spong-status.html create mode 100644 www/docs/spong.conf.html create mode 100644 www/docs/spong.groups.html create mode 100644 www/docs/spong.hosts.html create mode 100755 www/docs/spong.html create mode 100644 www/docs/spong.message.html create mode 100644 www/docs/spongfaq.html create mode 100644 www/docs/spongindex.html create mode 100644 www/docs/spongtoc.html create mode 100755 www/docs/todo.html create mode 100755 www/docs/user-guide.html create mode 100644 www/docs/www-spong-ack.html create mode 100755 www/docs/www-spong.html diff --git a/www/docs/admin-guide.html b/www/docs/admin-guide.html new file mode 100755 index 0000000..19a37b0 --- /dev/null +++ b/www/docs/admin-guide.html @@ -0,0 +1,524 @@ + + + + + + +admin-guide + + + + + +

admin-guide

NAME +
DESCRIPTION +
INSTALLATION +
- Installation - Server +
- Installation - Client +
+
CONFIGURATION +
- Configure Web Server +
- TCP Wrappers +
+
DEBUGGING +
- spong-server +
- spong-client +
- spong-network +
- spong-message +
+
WWW-SPONG +
+
SPONG-NETWORK +
- Service Checks +
- Service Check Flags +
+
SEE ALSO +
AUTHOR +

NAME

+admin-guide - Spong Administrator's Guide +

DESCRIPTION

+This document is for Spong Administrator. It details how to install and +configure the Spong Server and Spong Client programs. +

INSTALLATION

Installation - Server

+To build and install the spong server do the following on the machine +that is to be the Spong Server. It is suggest that your have web server +running on the same machine for the spong web display program. It is not +required, but it will simplify the installation. +

+
+Edit the "build" script, and set the variables at the top of that script +according to where you want spong installed, and where certain programs +that spong relies on are located. +
+
+
+
+Check to make sure there is a config/spong.conf.<os> file corresponding +to your operating system, if not - create one. This file contains paths and +command line arguments to helper programs that are used to determine things +like disk usage, etc... If you have to create your own spong.conf.<os> +file, then please email it to me so that I can add it to the distribution. +
+
+
+
+Make sure you are in the directory that you unpacked spong in and type: +./build os where <os> is the name corresponding to your +operating system. You can type ./build help to generate a list of +valid operating system strings. +
+
+When the build completes, you will be left with some new directories +in the folder that you unpacked spong in. The build process takes the spong +source (and documentation), and replaces some "tokens" with values that +you have supplied at the top of the build script. The build process also +creates a spong.conf file, and generates various types of documentation +based on the POD files that come with spong. +
+
+
+
+Now, type ./build install. Note that the install process makes +no assumptions about what user you want to run spong as (you don't +have to run it as root). This means that you have to be a little more careful +when you install spong (making sure it has the correct permissions, and +that you have permission to copy the www pages into your web server's document +tree). +
+
+
+
+Now edit the spong.conf, spong.hosts, spong.group and spong.messages files +that you just installed and season to taste. You should now be able to +read the manual pages for each. +
+
+

+Now you will have the executables and configuration files in place +on the server. You need to start the spong-server and spong-network programs. +The spong-server program will listen for reports from various agents, and +the spong-network program will start testing the hosts you have defined +for any problems. After starting those programs, you should start seeing +files show up in the $SPONGDB directory that you defined in the spong.conf +file. +

+NOTE - HOSTNAMES: Part of spong-server's status message authentication has +to do with host names. spong-server checks the host name in a status message +against the hosts defined in the spong.hosts file. The the status message host +name is not found, spong-server will silently drop the messages. +

+So it is important that your serves are able to resolve their fully qualified +domain name. To do this check there is a little Perl test program +gethost-test from in the /utils directory of the Spong distribution. Just +run it from a command line by entering perl gethost-test. It tests to see is +the host can resolve it's fully qualified domain name. If it can't then it +will advise you on ways to fix the problem. See also Question 2 in the Spong FAQ. +

Installation - Client

+For each client machine you will need to install the the package just like a +the server installation described above. After the ./build install step +is done, you can remove a number of directories that are not needed by +spong-client. (Assuming a standard installation directory). +

www/ +
cgi-bin/ +

+ +The only configuration file that you have to edit is the etc/spong.conf (and +etc/spong.conf.>host> files(s). +

+If you have a number of like clients with the same OS your can copy +the entire installation directory tree from an installed client to other +clients. You can use tar+ftp, rcp, rdist or whatever mechanism you would +normally use. Just be sure the Spong installation directory into the same +location as the original client. +

CONFIGURATION

Configure Web Server

+To use the Spong Web Display your need to configure you web server in +conjunction with some configuration variable in the spong.conf configuration +file. +

spong.conf +

$WWWSPONG +: +This is the URI path to the location of the www-spong CGI program in the web +server's document tree. For example, if the URL of www-spong is going to be +http://www.example.org/spong/cgi-bin/www-spong, you need to set $WWWSPONG +to '/spong/cgi-bin/www-spong'. See also the section on Spong CGI Directory elsewhere in this document. +
$WWWACK +: +This is the URI path to the location of the www-spong-ack CGI program in the +web server's document tree. For example, if the URL of www-spong is going to be +http://www.example.org/spong/cgi-bin/www-spong-ack, you need to set +$WWWSPONG to '/spong/cgi-bin/www-spong-ack'. See also
the section on Spong CGI Directory elsewhere in this document. +
$WWWGIF +: +This is the URI path to the location of the SPONG/www/gifs/ directory in the +web server's document tree. If the location of the images directory is +http://www.example.org/spong/gifs/, then $WWWGIF is set to '/spong/gifs'. +See also the section on Spong HTML Directory elsewhere in this document. +
$WWWHTML +: +This variable is used as a part of the Spong online help/information system. +The variable is different from the other $WWW spong config variables. This +variable is set to the actual file location of the SPONG/www/html directory +on the file system. The Web Display programs reads the requested files, does +some token replacement, and send the files to the web server. +
$WWDOCS +: +This variable is used as a part of the Spong online help/information system. +The variable is different from the other $WWW spong config variables. This +variable is set to the actual file location of the SPONG/www/docs directory +on the file system. The Web Display programs reads the requested files, does +some token replacement, and send the files to the web server. +

Web Server Configuration +

+On the web server side of thing your will have to configure two items: the +SPONG/www directory and the SPONG/cgi-bin/ CGI directory +

Spong CGI Directory +

+The SPONG/cgi-bin/ directory must be setup as a CGI directory and alias-ed +into the desired location. For example, for Apache a sample configuration +line would be: +

+  ScriptAlias /spong/cgi-bin/ /usr/local/spong/cgi-bin/
+

Spong HTML Directory +

+The SPONG/www/ directory must be alias-ed into the desired location within +the web server document tree. If you want the SPONG/www directory +to be under http://www.example.org/spong/ on an Apache web server, use this +configuration line: +

+  Alias /spong/ /usr/local/spong/www/
+

TCP Wrappers

+The spong-server can use the TCP Wrappers library to validate incoming +connection. The use of TCP Wrappers is optional. It is not required. +

+To use the TCP Wrappers library, the Authen::Libwrap Perl module must be +installed on the Spong Server host. The Authen::Libwrap module can be found +in the Comprehensive Perl Archive Network (http://www.cpan.org/). +

+The service names for the hosts_allow and hosts_deny files are as follows +

spong-update +: +The service that Spong Client programs use to send status update messages. +
spong-bb-update +: +The Big Brother (http://bb4.com) Server Emulation. BB Clients use this service +for sending status update messages. +
spong-query +: +Service that Spong Display clients use for Spong Database queries +
+

DEBUGGING

+The general way to debug Spong programs is to use the --debug # parameter. +The # is a number from 1 to 9 that controls the amount of debugging that is +printed. The higher the number the more detail that is output. This force the +program to run in the fore-ground, (if it daemonizes itself) and the program +will print out a lot of debugging statements. Also each program updates it's +command line buffer with the current status which can be viewed in the ps +command. +

+If $SPONG_LOG_FILE or $SPONG_LOG_SYSLOG are set in the spong.conf file +the programs will log errors to a log file and/or syslog , respectively. The +file are named program-name.log in the $SPONGTMP directory and the +entries are logged to syslog under the USER facility with a priority of ERR. +

spong-server

+When spong-server is run with --debug # the primary process will run in the +fore-ground and all of the child processes with write their debugging +statements to the screen. The query processing will print out all of the +database queries with the type of data requested and in what format. The +spong update and Big Brother update process will print out +host/service/color of every status message that is received. +

+The update processes will print out their actions concerning notifications. If +a notification is indicated, spong-server will call spong-message with +the --debug parameter if --debug level is at least 3. +

spong-client

+spong-client will print out the check that is being performed along with +the status and the summary message. +

spong-network

+spong-network will print out the current host that is being checking and the +name of the check as it performs them, along with the status and the summary +message. +

spong-message

+spong-message can be tested outside of spong-server to test your notification
+configurations. Your run spong-message with the following parameters:
+
+    spong-message --debug color host service time "Summary message"
+

+where: +

time +: +a number which is the date/time in epoch format (i.e. +the number of seconds since 00:00 01/01/1970). Just pick a big number. +

+spong-message will print out the current rule number (starting with 0). +The the success or failure of all of the checks of the matching +attributes. +

+After the rules matching phase, spong-message will then print out all of the +people being notified and how they are being notified. spong-message can +potentially print out a large quantity of debugging. You may want to redirect +the output to a file while you are testing it. +

WWW-SPONG

Customizing Web Pages

+Spong has a feature that allows users to customize some aspects of the Spong +web pages. If a header and/or footer template file exist, the contents of the +field will be display as a header or footer of every web page generated. The +header or footer files should be placed in the /html directory where the +Spong www/ directory was installed (the $IWWW variable from the build +program) and named "header.html" or "footer.html", respectively. +

+Place the HTML code that you want display into the template files. +You can also specify other HTML files to be included when the file is +display. Insert the string "!!WWWSHOW!!/filename" into +the place that your desire the file named "filename" to be display. The +file to be include should placed into the same directory are the "header.html" +or "footer.html" file resides. +

+Note: This customization feature is limited in the current release. +More substitution variables (i.e. hostname, service, status, etc) +will be added into future. As will the ability to select which type of +pages the headers or footer will be placed (i.e. service status screen, +server display screen, history screen, problem screen, etc.) +

Expanded Host Status Pages (Information Files)

+This feature is one of Spong's best kept secrets. You can create additional +information files that will be displayed on all status displays for a +particular host. To use this feature, you first have to create an info +directory in a host's database directory (i.e. +$SPONGDB/hostname/info/). Then you place the +documentation files that will displayed into that directory. the spong-server manpage +looks for the the following files: +

$SPONGDB/<hostname>/info/info.txt +
$SPONGDB/<hostname>/info/info.html +
$SPONGDB/<hostname>/info/info.brief.txt +
$SPONGDB/<hostname>/info/info.standard.txt +
$SPONGDB/<hostname>/info/info.full.txt +
$SPONGDB/<hostname>/info/info.brief.html +
$SPONGDB/<hostname>/info/info.standard.html +
$SPONGDB/<hostname>/info/info.full.html +

+ +where <hostname> is the name of a host as defined in spong.hosts. See +the spong.hosts manpage for most information. +

+spong-server first looks for a info.brief, info.standard or info.full file +depending on the type of display (brief, standard or full; and html or txt). If +the program finds one it will display that file. Otherwise, spong-server +will look for a info.txt or info.html file and then display that file as +a default. +

+The .txt files are used with text mode displays like those generated by the +spong display command (see the spong manpage). The .html files are used by the html +mode displays. The .html files can contain html code, URLs, embedded graphics, +Javascript, or anything that you display on a web page. +

Custom Contacts

+The web pages generated by Spong have "smart" "Contact Staff" links. That is, +the web page knows which host your are looking at when on your are looking at a +detailed status page. The spong-server generated a customize "Contact Staff" +link on a page's action bar that has the hostname and a message which contains +all of the current problems that system currently has. +

+The "Contact Staff" link URL consists of two parts. The first part is the +$WWWCONTACT from the spong.conf configuration file (see +the section on $WWWCONTACT in the spong.conf manpage). It contains the URL to your contact +staff CGI program that you must supply (see below). The second part of the are +the host name and the problem message passed as two form variables: host +and message respectively. +

+The $WWWCONTACT CGI program needs to handle two form variables (host and +message) and a couple of fields on a form for the user to fill out. A TEXT +field should be used to the host variable with a size of 50 characters of so +to handle big host names. The message field should be placed in a TEXT AREA +field. The size of the TEXT AREA field should be limited if the destinations +are pager. Most alpha-pages have a message limit of 150-250 characters. The +rest of the form should be populated with whatever fields that you need into +order to interface to your paging applications +

Customized Action Bars / Tool Bars

+The Action Bar of the Host and Service Status Displays (see the user-guide manpage +for more details) can be customized with the $WWW_ACTIONBAR_CUSTOM +configuration parameter (see the section on $WWW_ACTIONBAR_CUSTOM in the spong.conf manpage). Any HTML +code defined in this parameter will be included at the end of the Action Bars. +

+This parameter is preprocessed with the Perl eval function before the +contents are printed. This allows you to include complex Perl variables or Perl +code. Because of the eval processing you should use single quotes to enclose +the contents of this parameter. This will prevent premature evaluation of Perl +variables before the output. +

+If your do not need this customization, just leave $WWW_ACTIONBAR_CUSTOM +undefined. Nothing will be added to the Action Bars. +

Auto-Refresh

+The default of the spong-server is to not allow auto-refreshes if +@WWW_REFRESH_ALLOW and @WWW_REFRESH_DENY variables are empty (see +the spong.conf manpage). The spong-server the matches the REMOTE_ADDR, +REMOTE_HOST, and REMOTE_USER fields in the CGI environment against the +list of REFRESH_ALLOW expressions. If there is a match the session if ok'ed for +auto-refreshes. The server then checks the REMOTE_xxx fields against the +list of REFRESH_DENY expressions. A match here disallows auto-refresh even if +there was a previous match of a REFRESH_ALLOW expression. +

+For example, if @WWW_REFRESH_ALLOW contains[ 'joe', '.*-support', +'^192.168.12.*', 'noc-display' ] and @WWW_REFRESH_DENY contains +['bill','mary']. If a web browser on a machine at ip address 192.168.12.143 +queries the spong-server web pages, the auto-refresh would be allowed because +it matches the '^192.168.12.*' expression of @WWW_REFRESH_ALLOW. But if the +user was 'fred' at the same machine (192.168.12.143), auto-refresh would not be +enabled because 'fred' is in the I@<WWW_REFRESH_DENY> list. +

SPONG-NETWORK

Service Checks

+The service checks for a host are controlled by the services attribute +of the host's entry in the the spong.hosts manpage configuration file. services is a +list of services that will checks. The services are checked in the order they +are listed in services. +

+The services listed in services are actually spong-network modules, and meta-services names. The +spong-network modules do the actual network +service checks and meta-service names alter the default behavior of the +spong-network program. +

+At present there is only one meta-service: noping. +spong-network default behavior is to prepend a ping on to +the list in the services attribute. Putting noping in the list stops +this behavior. +

Service Check Flags

stop_after +

+The stop_after flag (the colon (':') ) can be appended to one, or +more, services in the services attribute for a host. If the check service +with the <stop_after> flag fails, all remaining services are skipped and set +with the clear status. +

+This stop_after flag is used to signal dependencies within the list +of tests specified in a services attribute. If the rpc portmapper service is +down, the NFS and NIS services on the system would be down also. There would be +no need to also check them. +

+For example:
+
+   'myhost.example.com' => { services => 'ping: ftp smtp http: webapp', },
+

+If the ping check for the host failed, the most likely reason is the host is +now out of communication with the Spong Network host. Checking the remaining +network services is not necessary. They would be reported as down and an number +of unnecessary notifications would have been sent out. The stop_after flag +will cause the remaining services to be reported as clear/not-available. +

+Similarly, the web server need to be running for a web-application to run. So +the http check is placed before the webapp check in services and it is +flagged with the stop_after flag. +

AUTHOR

+Stephen L Johnson <sjohnson@monsters.org> +

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:58:58 2002 + + + diff --git a/www/docs/check_interfaces.html b/www/docs/check_interfaces.html new file mode 100644 index 0000000..de7bed3 --- /dev/null +++ b/www/docs/check_interfaces.html @@ -0,0 +1,144 @@ + + + + + + +check_interfaces + + + + + +

Next:
check_snmp

Previous:
admin-guide

[Table of Contents]

[Index]

check_interfaces

NAME +
DESCRIPTION +
- Output Returned +
- Configuration +
+
EXAMPLES +
SEE ALSO +
NOTES +
RESTRICTIONS +
AUTHOR +

NAME

+check_interfaces - spong-network module to check for down intefaces via SNMP +

DESCRIPTION

+This is a plugin module for the Spong the spong-network manpage program. It is a core +Spong module. The check_interfaces module checks for down network interfaces +on a host by polling via SNMP. It reports any interfaces that are +administratively up but operationally not up. +

Output Returned

Status +: +If all interfaces are operationally up, a 'green' status is returned. If a host +is found to have no interfaces a 'yellow' status is returned. Any interfaces +that are operationally down and administratively up, a 'red' status is +returned. Any SNMP session problems will also result in a 'red' status being +returned. +
Summary Field +: +In normal operation, the status field will show "all interfaces up". If one or +more network interfaces are down, it will show "some interfaces are down". +Otherwise the summary field will have a description of what the problem or +anamoly is. +
Detail Message Field +: +In normal opereration the detail message field will have a list of all of the +network interfaces in the MIBII ifTable table along with the interface +description (ifDesc), type (ifType), administrative status +(ifAdminStatus) and operational status (ifOperStatus). Otherwise this +field will have a detailed description of the cause of an error. +

Configuration

SNMP Community Name +: +The default SNMP Community name is public. To provide an alternate default +SNMP Community name add it to the +$HOSTS_DEFAULTS entry in the spong.conf file +(i.e. $HOSTS_DEFAULTS{'snmp_community'} = 'secret';). +
+To override the default name on a per host basis, specify a snmp_ community +attribute in a host's entry in the %HOSTS variabile of the the spong.conf manpage +configuration file. See the the section on EXAMPLES elsewhere in this document section for a detailed +example. +
+
Ignored Interfaces +: +You can also specify a list of network interfaces for the check_interfaces +module to ignore. Add an 'ignore_interfaces' attribute to a host entry in +$HOSTS with a list of network interface to ignore. +
+A default list of interfaces to ignore is added an 'ignore_interfaces' entry +to the $HOSTS_DEFAULTS variable. A list of interfaces to ignore in all hosts +is created by adding an 'ignore_interfaces' entry to the $HOSTS_ALL varirable. +See the Examples section for a detailed example. +
+

EXAMPLES

+ %HOSTS = ( 'hostname.my-inc.com' => { 'services'  => 'interfaces',
+                                       'ip_addr'   => ['192.168.13.123'],
+                                       'community' => 'local-read',
+                                       'ignore_interfaces' => ['ppp1','ppp2'];
+                                       },
+            );
+
+ $HOSTS_DEFAULTS{'snmp_community'} = 'mysecret';
+
+ # Ignore the unused default intefaces on more servers
+ $HOSTS_DEFAULTS{'ignore_interfaces'} = ['et0','lan0'];
+
+ # Skip the loopback interface on the linux boxes
+ $HOSTS_ALL('ignore_interfaces} = ['lo0'];
+

NOTES

+The check_interfaces module use SNMP to poll a host. It retrieves the +ifIndex, ifDesc, ifType, ifAdminStatus, and ifOperStatus fields +for every entry in the ifTable table. The module then scans all of all of +the network interfaces inretrieved from the table. Any interface that is +administratively up and is not operationally up will result in an critical +status (red) being return. +

RESTRICTIONS

+check_interfaces uses the SNMP_Session, SNMP_utils and BER modules +from the SNMP_Session package. The SNMP_Session package must be installed +in order for this module to work. +

+The latest version of SNMP_Session package can be obtained from:
+
+  http://www.switch.ch/misc/leinen/snmp/perl/index.html
+

AUTHOR

+The original author is Mike Bayliss <mbayliss@datax.be>. Extra debug code +and enhancements added by Stephen L Johnson <sjohnson@monsters.org>. +

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:58:59 2002 + + + diff --git a/www/docs/check_snmp.html b/www/docs/check_snmp.html new file mode 100644 index 0000000..122793c --- /dev/null +++ b/www/docs/check_snmp.html @@ -0,0 +1,136 @@ + + + + + + +check_snmp + + + + + +

Next:
data_sendmsg

Previous:
check_interfaces

[Table of Contents]

[Index]

check_snmp

NAME +
DESCRIPTION +
- Output Returned +
- Configuration +
+
EXAMPLES +
SEE ALSO +
NOTES +
RESTRICTIONS +
AUTHOR +

NAME

+check_snmp - spong-network module to check for proper SNMP agent operation +

DESCRIPTION

+This is a plugin module for the Spong the spong-network manpage program. It is a core +Spong module. The check_snmp module checks for the SNMP agent running +in the host for proper operation. +

+The module check SNMP by issuing an snmpget operation for the systemGroup +table of the host. If the operation is sucessfully, snmp service is deemed +OK. The module also has an option check for the sysObjectId. An expected +sysObjectId value can be specified to be checked against the sysObjectId +value retrieved in the snmpget operation. If the values don't agree, a +critical (red) status is reported +

Output Returned

Status +: +If the snmpget operation is successfully, 'green' status is return. If an +SNMP error occurs a 'red' status is returned. +
+If an expect_objid is specified for the host, a 'green' status is returned +if the snmpget operation is successful and the sysObjectId value matches +the expect_objid. If the values don't match, a 'red' status is returned. +
+
Summary Field +: +If there are no problems, "snmp ok" is returned. Otherwise the summary field +will have a short description of that the problem or anamoly is. +
Detail Message Field +: +If normal operation the detail message will have the values of the system +description (sysDesc), uptime (sysUpTime), contact (sysContact), name +(sysName), location (sysLocation), and object id (sysObjectID) fields +from the System Group. If an expect_objid was specified for the host and the +retrived object id doesn't match, the expected value will also be listed. +Otherwise this field will have a detailed description of the cause of an error. +

Configuration

SNMP Community Name +: +The default SNMP Community name is public. To override the default name +specify a snmp_community attribute in a host's entry in the %HOSTS +variable in the the spong.conf manpage configuration file. See +the section on EXAMPLES elsewhere in this document for a detailed example. +
Expected System Object ID +: +You can specify an expected sysObjectID value to be checked against the +retrieved. Specify a expect_objid attribute in a host's entry in the +%HOSTS variable in the the spong.conf manpage configuration file. See the +Examples section for a detailed example. +

EXAMPLES

+ %HOSTS = ( 'hostname.my-inc.com' => { 'services'  => 'snmp',
+                                       'ip_addr'  => ['192.168.13.123'],
+                                       'snmp_community' => 'local-read',
+                                       'expect_objid' =>
+                                           '1.3.6.1.4.1.2021.250.10',
+          );
+

NOTES

+The check_snmp module uses an SNMP snmpget operation to poll a host. +It retrieves the values of the system description (sysDesc), uptime +(sysUpTime), contact (sysContact), name (sysName), location +(sysLocation), and object id (sysObjectID) fields from the System Group. +If the snmpget operation was successful, the snmp service is deemed OK. +

+If an optional expect_objid value is specified for the host, it will be +compared to the sysObjectID value retrieved from the host. If the values +don't match a critical ('red') status is generated. +

RESTRICTIONS

+check_interfaces uses the SNMP_Session, SNMP_utils and BER modules +from the SNMP_Session package. The SNMP_Session package must be installed +in order for this module to work. +

+The latest version of SNMP_Session package can be obtained from:
+
+  http://www.switch.ch/misc/leinen/snmp/perl/index.html
+

AUTHOR

+The original author is Mike Bayliss <mbayliss@datax.be>. Extra debug code +and enhancements added by Stephen L Johnson <sjohnson@monsters.org>. +

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:58:59 2002 + + + diff --git a/www/docs/data_sendmsg.html b/www/docs/data_sendmsg.html new file mode 100644 index 0000000..a9986d2 --- /dev/null +++ b/www/docs/data_sendmsg.html @@ -0,0 +1,90 @@ + + + + + + +data_sendmsg + + + + + +

Next:
developer-guide

Previous:
check_snmp

[Table of Contents]

[Index]

data_sendmsg

NAME +
DESCRIPTION +
- Configuration +
+
EXAMPLES +
SEE ALSO +
RESTRICTIONS +
AUTHOR +

NAME

+data_sendmsg - spong-network module that sends copies of update messages to +other spong-servers +

DESCRIPTION

+This is a plugin module for the Spong the spong-server manpage program. This module +sends incoming update messages to other spong-servers. It's purpose is to set +up regional Spong configurations that feed incoming status messages to +upper level Spong configurations. +

Configuration

$SENDMSG_SERVERS +: +A string that has the list of other Spong Servers that you want to the +status update messages to. The syntax is "hostname[:port] hostname[:port] ...". +If the :port is not specified, Spong::Status::SendMsg defaults to +$main::SPONG_UPDATE_PORT variable passed in the procedure call. See +the section on $SPONG_UPDATE_PORT in the spong.conf manpage for more details. +
@SENDMSG_INC_HOSTS +: +This is ia list of hosts who's status messages are sent to the other Spong +Server specified in $SENDMSG_SERVERS. These entries can be partial host names +or Perl regular expressions. +
@SENDMSG_EXCL_HOSTS +: +This is a list of hosts that should be exclude from send to the other Spong +Servers specified in $SENDMSG_SERVERS. These entries can be partial host names +or Perl regulare expressions. +

EXAMPLES

+ $SENDMSG_SERVERS = "spong-reg1.myinc.com:1998 spong-toplevel.myinc.com:1998
+                     spong-proxy.myinc.com:19980";
+
+ $SENDMSG_INC_HOSTS = ( '.*', );
+
+ $SENDMSG_EXCL_HOSTS = ( 'test1', 'test2', '.engr.myinc.com$', );
+

RESTRICTIONS

+data_sendmsg uses the Spong::Status library module to work. It uses the +new capability to send a status message to multiple servers. It is only +available in versions 0.02 and up of the Spong::Status module. +

AUTHOR

+Stephen L Johnson <sjohnson@monsters.org>. +

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:58:59 2002 + + + diff --git a/www/docs/developer-guide.html b/www/docs/developer-guide.html new file mode 100755 index 0000000..b388f32 --- /dev/null +++ b/www/docs/developer-guide.html @@ -0,0 +1,510 @@ + + + + + + +developer-guide + + + + + +

Next:
pre_redirect

Previous:
data_sendmsg

[Table of Contents]

[Index]

developer-guide

NAME +
DESCRIPTION +
PROTOCOLS +
- SPONG PROTOCOL +
- BIG BROTHER PROTOCOL +
+
MODULES +
- SERVER MODULES +
- CLIENT MODULES +
- NETWORK MODULES +
- MESSAGE MODULES +
+
CREATING MODULES +
Status Function +
SEE ALSO +
AUTHOR +

NAME

+developer-guide - developer's guide to Spong +

DESCRIPTION

+This is the developer guild to Spong. It documents the inner workings of the +client and server programs. It also describes the plug-in mechanism of the +spong-client and spong-network so that new check modules can be +developed for these programs. +

PROTOCOLS

+This section deals with the low level communication protocols that the clients +use to talk with the spong-server. The Spong and Big Brothers protocols +almost identical. They vary only in the data format. +

SPONG PROTOCOL

+The spong-server listens in on port 1998 for status updates from clients.
+After a socket has been opened, the client program sends a message with the
+following format:
+
+    command host service color time[:TTL] summary (\n)
+    detailed status message line 1 (\n)
+    detailed status message line 2 (\n)
+    ...
+    detailed status message line n (\n)
+

+Where: +

command +: +The command being sent to the spong server indicating +a type of update message or a change in operating status of the client. +
host +: +The fully qualified domain name of the host the message +is for. +
service +: +The name of the service that the update message is +for. +
color +: +The status color of the service (green - ok, yellow +- warning, red - alert). +
time +: +The date/time of the update message in epoch time format +(i.e. the number of seconds since 01/01/70, 00:00 AM) +
TTL +: +This optional field is the time to live, in seconds, for the status message. +Normally a will become stale (i.e. purple status) after 2 times $SPONGSLEEP +seconds which is the default. See the section on $SPONGSLEEP in the spong.conf manpage. This field will +override the default and keep the status message valid for a longer period of +time. +
summary +: +The status summary message field. A short and to the point message that +summarizes the status being returned. +
detailed status message +: +The remained lines of the message which will be the detailed information of the +status. Typically it can be the output of the df command or the top processes +by CPU utilization or the detailed responses of network checks. +

BIG BROTHER PROTOCOL

+The spong-server listens in on port 1984 for status Big Brother
+client updates. After a socket has been opens the client sends a message
+with the following format:
+
+    command host service color time summary (\n)
+    detailed status message line 1 (\n)
+    detailed status message line 2 (\n)
+    ...
+    detailed status message line n (\n)
+

+Where: +

command +: +The command being sent to the spong server indicating +a type of update message or a change in operating status of the client. +At present the only command defined is status which indicates a +service status update message. +
host +: +The fully qualified domain name of the host the message +is for. +
service +: +The name of the service that the update message is +for. +
color +: +The status color of the service (green - ok, yellow +- warning, red - alert). +
time +: +The date/time of the update message in standard date +format (i.e. Thu Jan 1 00:00:00 UTC 1970) +
summary +: +The status summary message field. +
detailed status message +: +The remained lines of the message +which will be the detailed information of the status. Typically it can +be the output of the df command or the top processes by CPU utilization +or the detailed responses of network checks. +

MODULES

+spong-client, spong-network, spong-message and spong-server use +various routines which are coded as modules. When the programs are +initializing, they determine which modules are going to be required. The +programs then go out and load each of the modules from the library directory. +When the modules are loaded they register themselves with the plug-ins +registry. The plug-in registry is the mechanism that the client programs use +to keep track of the modules into order to run them. +

SERVER MODULES

+spong-server has a hook that allows external programs access to the incoming +status updates coming from Spong client programs. The hook takes the form of +Server Data modules which are called after spong-server stores the status +update in it's database. +

+spong-server passes all of the information of the update message in addition +to the current event status duration to the Data Module. The modules should +do any processing that they need to do in as short a time as possible. This is +to minimize the resource overhead with lots of simultaneous status updates +arrive at same time. +

+Debugging messages and error messages can be printed by using the +&main::debug() and &main::error() functions respectively. If the module +develops a fatal error, it should terminate using the die() or croak() +functions depending on ones preference. Modules should just return upon a +successful invocation. +

+NEW +

+There are two new types of Spong Server plugin modules: predata and postdata +modules. The predata modules are called just after a message is received but +before the normal Spong processing is done. And a post module is called after +the Server's normal processing. i +

+Also in contrast to the old Spong Server data plugin modules all incoming +messages a sent to the new predata and postdata modules, not just status +messages. Predata modules can even flag a message to tell the Spong Server to +drop the message and ignore it. This will allow you a great deal more access +and control of the Server's incoming message processing. +

+Modules are called a predictable, controlable order. There are run in the order +of the sorted registry hash keys. This allows you to create modules that have +run dependencies. +

+And there is a new API to go along with the new modules. Now parameters are +passed in a Perl hash. This simplifies the module interface to the server. The +message type is determined by the cmd field. Message hash details are +in the the spong-server-mod-template manpage document. +

+See the spong-server-mod-template manpage for an example of how to code a +spong-server Server Data Modules +

CLIENT MODULES

+Client modules define checks which are to be done on the host that the +spong-client program is running on. The module's check function is called +without any parameters. Client modules are expected to issue any systems +command and parse the output in order to determine the service status. +

+Any threshold variables needed for warning and alert level trigger need to be +defined and placed into the SPONG/etc/spong.conf file. The threshold +variable need to be uniquely named and should be named according to the type of +check being done (i.e. $DISKWARN or $DFWARN for disk checks and $CPUWARN for +CPU checks, etc.). +

+Once the service status and messages have been determined the module +can call the &main::status() function in order to send the +information back to the spong-server. See the section on Status Function elsewhere in this document for more +information. +

NETWORK MODULES

+Network modules defined checks that to be done on hosts over the network +to ensure that a network service is running. The modules are called with +the name of the host the check is to be done to. The modules is also expected +to put an alarm wrapper around the code that performs the check. This is +to prevent excessive delays dues to lost communications. It is suggested +that 10 seconds be used for the alarm setting. +

+The module should not call the &main::status() function directly. +spong-network has a mechanism for rechecking services that are reported down +on an initial check. If the recheck mechanism is engaged, "red" statuses will +be downgraded to "yellow" until a failure count threshold is reached. The the +services will be reported as "red". +

+After the status condition has been determined the check function should return +three parameters: +

STATUS +: +The status color either "red", "yellow", or "green". +
SUMMARY +: +A short line line summary of the status +
MESSAGE +: +more detailed information (can be multi-lined) +

+These parameters are the same that will be passed to the &main::status() +command. See the section on Status Function elsewhere in this document for more information on these parameters. +

+The network modules have two support functions available, +&main::check_tcp() and &main::check_simple(), which can +simplify simple TCP port checks. +

+&main::check_tcp( host, port, data ); +

+Where the arguments are: +

HOST +: +The name or ip address of the host to be checked. +
PORT +: +The name, or port number, of service to connect with. +
DATA +: +The data to be send to the host after the port is opened. +

+The function &main::check_tcp() will make a connection to +the given PORT on the HOST and send a message (DATA). It then returns what +it gets back to the caller. +

+&main::check_simple( host, port, send, check, service) +

+Where the arguments are +

HOST +: +The name or ip address of the host to be checked. +
PORT +: +The name of the port to connect with. +
SEND +: +The message to sent to the host after the port is opened. +
CHECK +: +A perl regular express to be used to validate the response return +by the host. +
SERVICE +: +The name of the service being check. It is used in the summary +and detailed status messages. +
+The function &main::check_simple() is a generic TCP port checking +routine. This will go out connect to a given port (using &main::check_tcp()) and +check to make sure you get back expected results. The function returned +three parameters: STATUS, SUMMARY and MESSAGE as detailed above. The return +values of this function can returned as the necessary returned values of +the check module. +
+

MESSAGE MODULES

+Message modules are function called to send a notification message to +a contact on a specific service or service. The messaging functions are called +with an the contacts identifier for the messaging service (i.e. the page PIN +code of a paging provider). The messaging module is expected to take care of +all of the data formating and communications logic to send a notification +message to the contact. +

+The messaging functions has access to these global variable in order format +a notification message: +

$color +: +The status color of the message +
$host +: +The fully qualified domain name of the host +
$time +: +The date and time of the message being sent. (format is +epoch time or time()) +
$message +: +A one line summary status line +
$duration +: +The current duration of the current status in seconds. +(a zero duration indicates a change in status) +

+There are two support functions that be used to format a message and send the +message via e-mail: &main::email_status() and +&main::email_mini_status(). Both functions format e-mail message to be +send to RECIPIENTS, but email_mini_status() sends out a shorter mail message +which is more suitable for SMS and smaller alpha pagers. +

+Both functions are called thusly: +

+&main::email_status( recipient, flags ) +

+&main::email_mini_status( recipient, flags ) +

+Where the arguments to the functions are: +

RECIPIENT +: +one or more e-mail recipients which placed in the to: line +of the mail message. +
FLAGS +: +flags to alter the formating of the message. +

+The only flag current defined is 'shortsubject'. This prevents $color, +$hostname, and $summary from being placed on the "subject:" line. +

CREATING MODULES

+Creating the actual modules is very trivia to do. Create your module by +following the appropriate template from below. +

+Then place your template module file into the appropriate directory below. +

+
+spong-client - LIBDIR/Spong/Client/plugins +
+
+
+spong-network - LIBDIR/Spong/Network/plugins +
+
+
+spong-message - LIBDIR/Spong/Message/plugins +
+
+
+spong-server - LIBDIR/Spong/plugins +
+

+Then test your modules by running the program with the --debug parameter to see +if it is operating properly. +

Status Function

+&main::status( SERVERADDR, HOST, SERVICE, COLOR, SUMMARY, MESSAGE ) +

+The arguments to the &main::status() function are: +

SERVERADDR +: +Should be $SPONGSERVER. +
HOST +: +The full hostname of the machine being reported. +
SERVICE +: +The a short name that describes the service +that you are reporting on. +
COLOR +: +The color of the status being reported, either "green", "yellow", or "red". +"green" denotes an OK status, there are no problems and everything is within +normal parameters. "yellow" denotes a warning status, a abnormal situation that +has which may be need to be looked at or a parameter has changed (up or down) +towards a critical level. "red" denotes an alert status, a critical situation +that has arisen and needs immediate attention or a parameter has changed (up +or down) to a critical level. +
SUMMARY +: +A short one line summary of the status. This should be a short and concise +summary of the current situation of the service. The simplest form is to +say "Service is OK" or "Service is down". Another form is to display current +information (like system uptime, number of job and users) and additional +text for warning and alerts (i.e. "uptime - 123, jobs - 123, users - 123, cpu +load level is at 3.2"). +
+If you are reporting on multiple sets of like items (like file partitions or +processes), report the names of those items that are abnormal, (i.e. +"filesystems: / at 99%, /tmp at 100%"). +
+
MESSAGE +: +This is the place to put detailed information about the status of the service. +Typically this will be the output of the system commands or function calls. For example, it could be the 10 jobs by cpu usage in a ps command, or the output +of a df command for disk checking. +
+There are no limitations on the contexts of the field. You can include URL's +that link to another monitor package or take you to an administration web page +for the service in question. +
+

AUTHOR

+Stephen L Johnson, <sjohnson@monsters.org> +

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:00 2002 + + + diff --git a/www/docs/pre_redirect.html b/www/docs/pre_redirect.html new file mode 100644 index 0000000..c91314f --- /dev/null +++ b/www/docs/pre_redirect.html @@ -0,0 +1,64 @@ + + + + + + +pre_redirect + + + + + +

Next:
spong

Previous:
developer-guide

[Table of Contents]

[Index]

pre_redirect

NAME +
DESCRIPTION +
- Configuration +
+
EXAMPLES +
SEE ALSO +
RESTRICTIONS +
AUTHOR +

NAME

+pre_redirect - spong-network predata module that redirects update messages +to other spong-servers +

DESCRIPTION

+This is a pre data plugin module for the Spong the spong-server manpage program. This +module redirects incoming update messages to other spong-servers. It is used to +selective redirect certain status messages to another Spong Server Host or +another Spong Server instance. +

Configuration

EXAMPLES

RESTRICTIONS

+pre_redirect uses the Spong::Status library module to work. It uses the +new capability to send a status message to multiple servers. It is only +available in versions 0.02 and up of the Spong::Status module. +

AUTHOR

+Stephen L Johnson <sjohnson@monsters.org>. +

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:00 2002 + + + diff --git a/www/docs/spong-ack.html b/www/docs/spong-ack.html new file mode 100644 index 0000000..a318714 --- /dev/null +++ b/www/docs/spong-ack.html @@ -0,0 +1,172 @@ + + + + + + +spong-ack + + + + + +

spong-ack

NAME +
SYNOPSIS +
DESCRIPTION +
OPTIONS +
CONFIGURATION +
- Configuration Files +
- Configuration Variables +
+
FILES +
EXAMPLES +
DEPENDENCIES +
BUGS +
SEE ALSO +
AUTHOR +
HISTORY +

NAME

+spong-ack - Spong acknowledgment tool +

SYNOPSIS

+spong-ack [--debug] [--batch] host services time [message] +

+spong-ack [--debug] --delete ack-id +

DESCRIPTION

+When a spong event occurs (or will occur), you can use this tool to acknowledge +that you know that there is a problem. You can provide text that will be seen +by others looking at the event (via a spong display program). You can specify +at time limit that the problem will occur. If a problem has been acknowledged, +you will no longer received notifications of the problem, and the display +programs will show the status of the service as "blue". +

OPTIONS

--debug +: +Print debugging statements. This option can be specified while creating or deleting acks. +
--batch +: +Print the ack-id instead of the normal output. The primary use of this parameter +is for scripts. An ack can be created when a job that runs causes a service to +temporarily exceed it's normally limits, or if a service is taken down for an +unknown or irregular length of time. +
--delete +: +Delete a previously created ack. +

+Here is a description of the arguments for creating acks: +

host +: +The host having the problem(s) you are acknowledging. +
service +: +The service or services (separated by ".") or all services that your are +acknowledging. +
time +: +The that the acknowledgement will late. This can be an offset "+1h, +3a,d +1w" or +an absolute date and/or time indicator "12/25/1997 14:00:00. The date needs to be +a 4 digit year, and the time needs to be in 24 hour format. +
message +: +An optional message that will appear to those viewing the state of the host with a +spong display program. If the value is "-", then the message will read from STDIN. +

+Here is a description of the arguments for deleting acks: +

ack-id +: +The acknowledgment id to delete. The id can be obtained by using the --batch +parameter when creating the acknowledgment, or by using the the spong manpage command +with the --brief and --ack parameters. +

CONFIGURATION

Configuration Files

+spong-cleanup reads the standard spong.conf and spong.conf.<host> +configuration files. +

Configuration Variables

$SPONGSERVER +: +The host that at least the the spong-server manpage and the spong-message manpage +programs are running on. Typically the the spong-network manpage program runs on that +host as well. +
$SPONG_UPDATE_PORT +: +This variable defines the port that the the spong-server manpage update process listens +on. If this variable is not defined on the $SPONGSERVER host, the +the spong-server manpage update process will not be started. The default value is 1998. +

FILES

+SPONGHOME/etc/spong.conf, SPONGHOME/etc/spong.conf.<host> +

EXAMPLES

+   spong-ack mailhub.my-inc.com all '05/27/2000 06:00:00' 'Server is being upgraded'
+
+   spong-ack www5.my-inc.com http +1h 'Web server is randomly dying. Investigating.'
+

+In a shell script:
+
+  ...
+  HOST=`hostname`
+  ACKID=`spong-ack --batch $HOST cpu +8h 'Database exports are running'`
+  ...
+  # Database exports are done here
+  ...
+  spong-ack --delete $ACKID
+  ...
+

DEPENDENCIES

+Perl v5.005_03 or greater is required. +

BUGS

+No know bugs. +

AUTHOR

+Stephen L Johnson <sjohnson@monsters.org> +

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

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:01 2002 + + + diff --git a/www/docs/spong-cleanup.html b/www/docs/spong-cleanup.html new file mode 100644 index 0000000..0858517 --- /dev/null +++ b/www/docs/spong-cleanup.html @@ -0,0 +1,133 @@ + + + + + + +spong-cleanup + + + + + +

spong-cleanup

NAME +
SYNOPSIS +
DESCRIPTION +
CONFIGURATION +
- Configuration Files +
- Configuration Variables +
+
FILES +
DEPENDENCIES +
BUGS +
SEE ALSO +
AUTHOR +
HISTORY +

NAME

+spong-cleanup - perform nightly maintenance to the spong database +

SYNOPSIS

+spong-cleanup +

DESCRIPTION

+This program performs routine, regular maintenance of the spong database. +

+
+Cleans out any history older then 7 days. It moves the old history for +each host into the $SPONG_ARCHIVE directory. If +you don't think you would ever want to get at that history, then you can just +change the script so that it is deleted. +
+
+
+* Removes any acknowledgements that are no longer valid. +
+
+
+* Removes any services that don't seem to be reported any more (if you +stop monitoring something on a machine - the old entry will still hang around +and show up as purple). +
+

+The spong-cleanup program should be run every night as a cronjob. This will +ensure that database queries are speedy especially the History Log displays. +

CONFIGURATION

Configuration Files

+spong-cleanup reads the standard spong.conf and spong.conf.<host> +configuration files. +

Configuration Variables

$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. +
$SPONG_ARCHIVE +: +The directory where to put old history file entries for each host. Each host +has 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. +

FILES

+spong.conf, spong.conf.[hostname] +

DEPENDENCIES

+Perl v5.005_03 or greater is required. +

BUGS

+None know bugs. +

AUTHOR

+Ed Hill <ed-hill@uiowa.edu>, Unix System Administrator, The University of +Iowa +

+Stephen L Johnson <sjohnson@monsters.org> +

HISTORY

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:01 2002 + + + diff --git a/www/docs/spong-client-mod-template.html b/www/docs/spong-client-mod-template.html new file mode 100755 index 0000000..5ac1191 --- /dev/null +++ b/www/docs/spong-client-mod-template.html @@ -0,0 +1,129 @@ + + + + + + +spong-client-mod-template + + + + + +

Next:
spong-intro

Previous:
spong-client

[Table of Contents]

[Index]

spong-client-mod-template

NAME +
DESCRIPTION +
SEE ALSO +
AUTHOR +
HISTORY +

NAME

+spong-client-mod-template - how to create modules for spong-client +

DESCRIPTION

+This document describes how to create your own plug-in modules for +the spong-client program. Your modules can be your own new custom check or +they can replacements for the core Spong modules. +

+This template assumes that you are creating a new client check +called 'mailq'. The name of the file created should be 'check_mailq'. The +file name for spong-client modules should always be 'check_' plus the +registry name (e.g. for the foo check, the registry name is 'foo' and the file +name is 'check_foo'). +

+The line that has the assignment to $CHECKFUNC{'registry-name'} is the +key to the registry mechanism. It's what ties the registry name to the +actual checking function. +

+The registry name does not always have to match up to the service name as in +this case of out module 'mailq'. If you where creating a new and improved +function to check mail queues, you could create a module called 'my_mailq'. You +would use the registry name 'my_mailq', but you would use the service name +'mailq' in the &status() function when reporting your info back to +the server. +

+check_mailq:
+
+  # Register my routine with plug-in registry
+  $CHECKFUNCS{'mailq'} = &check_mailq;
+
+  # Sendmail mail queue check for mail servers. It checks the number of mail
+  # message queued against the $MAILQWARN AND $MAILQCRIT variables.
+  # It runs the command in the config variable $MAILQ to do it's check.
+
+  sub check_mailq {
+     my($mqcnt, $message, $color, $summary );
+
+     open (FOO,"$MAILQ |");
+
+     $mqcnt = 0;
+     while (<FOO>) {
+        if (/Mail Queue\s+\((\d+)/) { $mqcnt = $1; }
+
+        # Grab enough to get the first 10 entries.
+        if (++$lines <= 35) { $message .= $_ };
+     }
+     close FOO;
+
+     $color = "green";
+
+     if ($mqcnt > $MAILQWARN) { $color = "yellow"; }
+     if ($mqcnt > $MAILQCRIT) { $color = "red"; }
+     $summary = "Mail Queue count = $mqcnt"
+
+     &main::debug("mailq - $color, $summary")
+     &main::status( $SPONGSERVER, $HOST, "mailq", $color,
+                    $summary, $message );
+
+  }
+
+  # I'm include perl code, I need this line.
+  1;
+

+Please note the final line. It is always required for a module file. +

+The $MAILQWARN and $MAILQCRIT variables are added to the spong.conf +or spong.conf.<hostname> configuration files. These variable define +the warning and alert threshold levels for your custom check. +

+Configuration variable for your custom checks should be named to match them up +with the name of your customized check. In our case, we started our variable +names with MAILQ with matches up nicely with our module name of 'mailq'. Naming +the threshold variables $WARN_SPOOL_LEVEL and $CRIT_SPOOL_LEVEL would have made it unclear as to which check they belonged to. Keep the names similar, it will +make it easier on you and others to administer your setup in the future. +

AUTHOR

+Stephen L Johnson <sjohnson@monsters.org> +

HISTORY

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:02 2002 + + + diff --git a/www/docs/spong-client.html b/www/docs/spong-client.html new file mode 100755 index 0000000..e838bce --- /dev/null +++ b/www/docs/spong-client.html @@ -0,0 +1,284 @@ + + + + + + +spong-client + + + + + +

Next:
spong-client-mod-template

Previous:
spong-cleanup

[Table of Contents]

[Index]

spong-client

NAME +
SYNOPSIS +
DESCRIPTION +
+
CONFIGURATION +
- Configuration Files +
- Configuration Variables +
+
FILES +
EXAMPLES +
DEPENDENCIES +
BUGS +
SEE ALSO +
AUTHOR +
HISTORY +

NAME

+spong-client - report system information to spong server +

SYNOPSIS

+spong-client [ --debug|-d n ] +[ --kill|--restart|--nosleep|--norefresh ] config-file +

DESCRIPTION

+This program is run on each Unix 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% of the total you have specified, to keep clients from sync'ing +up and overloading the spong-server). +

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

Format of update messages

+It sends a message for each check to the spong server and reports the +following: +

hostname (where is this report coming from)
+
service name ("disk", "cpu", "procs", "logs", "local")
+
color ("red", "yellow", "green")
+
a one line summary
+
a more detailed message providing additional detail.
+

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

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

+The more detailed message contains information such as the complete +df output, or a listing of the top 10 processes sorted by CPU. +

Running the program

+You should start this program in your system startup file, and it should be +running constantly. If no parameters are specified, spong-network forks +and detaches itself to run as a daemon. +

+If you provide the --debug n flag, then debugging information will be +printed to stdout, otherwise output will only be produced if there is a +problem. Where n is a number from 1 - 9. A higher number means more +verbosity in the debugging output. +

+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 flag causes the program to cycle through all +of the checks once then exit. These flags can be used to run spong-client as a +cron job (depreciated), this reduced the effectiveness of the check_logs +module. +

Client Checks

+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 $CHECKS +configuration variable. Upon initialization, spong-client will load the +modules defined in $CHECKS from the LIBDIR/Spong/Client/plugins/ +directory. As each modules is initialized, it registers itself with the the +plugins registry (see the Developer Guide). +

Extending Functionality

+Depreciated, please refer to the section on CLIENT MODULES in the developer-guide manpage. +

+If you want to check some service which is not being checked by spong-client, +then you can define a &check_local() function in your +config file (either in your standard the spong.conf manpage config file or your host specific spong.conf.hostname +file - but not both!). That function can do anything you want, but at the +end needs to call the &status() function to report +what you have found to the spong server. +

CONFIGURATION

Configuration Files

+By default this reads the the spong.conf manpage 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. +

+After reading the configuration file that you specify (or the default), +it then reads the spong.conf.[hostname] file where [hostname] 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. +

Configuration Variables

+Here is a listing of the configuration variables applicable to the +spong-client program. +

$SPONGSLEEP, $SPONGSERVER, $SPONG_UPDATE_PORT +

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

$SPONGSLEEP{'DEFAULT'}, $SPONGSLEEP{'spong-client'} +

+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 +$SPONGSLEEP{'DEFAULT'} value. If no value is then found, spong-client +fall back to using $SPONGSLEEP. +

$SPONGTMP +

+The directory that Spong programs use for temporary store and work files. It +should be different directory than /tmp for operation and security reasons. +

$SPONG_LOG_FILE +

+If set to 1, spong-client will log errors to a log file in $SPONGTMP +named spong-client.log. +

$SPONG_LOG_SYSLOG +

+If set to 1, spong-client will log errors to the syslog using the +USER facility and the ERR priority. +

$CHECKS +

+A string that has the list of client check modules to run. If $CHECKS is +missed or blank, spong-client defaults to "disk cpu processes logs". If the +check_local() function is present then 'local' is appended. +

$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 +
checks +: +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 (in seconds) that each event is to be reported to the server +
text +: +a string which is the the text to be reported +back in the detailed message field of the status report (which can include +match position variables from pattern) +
id +: +an optional key field to associated with each event generated. The default +key is the evaluated text field. An id key may be specified for the +for a check pattern. All hits of the pattern will be consolidated into one +event. The data of the last hit will be reported in the event. +

$DF, $UPTIME, $PS, $GREP +

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

FILES

+spong.conf, spong.conf.[hostname] +

EXAMPLES

+        spong-client --debug 5 --nosleep
+        spong-client --debug 5
+        spong-client --restart
+

DEPENDENCIES

+Perl v5.005_03 or greater is required. +

BUGS

+None know bugs. +

AUTHOR

+Ed Hill <ed-hill@uiowa.edu>, Unix System Administrator, The University of +Iowa +

+Stephen L Johnson <sjohnson@monsters.org> +

HISTORY

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:02 2002 + + + diff --git a/www/docs/spong-intro.html b/www/docs/spong-intro.html new file mode 100644 index 0000000..a2a9038 --- /dev/null +++ b/www/docs/spong-intro.html @@ -0,0 +1,485 @@ + + + + + + +spong-intro + + + + + +

Next:
spong-message

Previous:
spong-client-mod-template

[Table of Contents]

[Index]

spong-intro

NAME +
DESCRIPTION +
Availability +
SUPPORT +
DEPENDENCES +
DOCUMENTATION +
FILES +
LICENSING +
CHANGES +
ACKNOWLEDGMENTS +
- By Ed Hill +
- by Stephen L Johnson +
+
BUGS +
- Known Problems in v2.6 +
+
AUTHOR +

NAME

+Simple System/Network Monitoring - spong v2.0 +

DESCRIPTION

+This is a simple systems and network monitoring package called Spong. It +has the following features: +

+
+client based monitoring (CPU, disk, processes, logs, etc...) +
+
+
+monitoring of network services (smtp, http, ping, pop, dns, etc...) +
+
+
+grouping of hosts (routers, servers, workstations, PCs) +
+
+
+rules based messaging when problems occur +
+
+
+configurable on a host by host basis +
+
+
+results displayed via text or web based interface +
+
+
+history of problems +
+
+
+verbose information to help diagnosis problems +
+
+
+easily expandable via a plug-in module facility +
+

+This is hopefully a 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 (including NT - although it has not been ported yet - +but is on the to-do list). +

+I'm a strong believer in KISS (keep it simple stupid), and hopefully +this package is as simple as possible (but no simpler). Spong is broken +up into components that each do a specific thing. Listed are some of the +(key) components: +

+
+spong +
+
+Text based query program, reports information about hosts that are +monitored. +
+
+
+www-spong +
+
+Web based query program, reports information about host that are monitored. +
+
+
+spong-client +
+
+Program that runs on each monitored server. Reports host based information +(disk, cpu, logs, etc.) +
+
+
+spong-network +
+
+Reports on network based services (smtp, ping, http, etc.) +
+
+
+spong-server +
+
+Collects information reported and responds to queries about that information. +
+
+
+spong-message +
+
+Called by the spong-server program to send out notifications when +problems occur. +
+

Availability

+Spong's Home Page is at http://spong.sourceforge.net/. +

+Perl is require to run spong. If you don't have Perl installed you can retrieve +it from the CPAN archive http://www.cpan.org/CPAN/, along with other +optional modules such at the Net::DNS module. I would suggest having at least +version 5.004 installed (otherwise you will need to download the CGI.pm module +as well). You can get the latest version of Perl at +http://www.perl.com/CPAN/src/latest.tar.gz +

+You can retrieve the latest version of Spong from the Spong project at Source +Forge. The 'Downloads' web is at http://spong.sourceforge.net/downloads.html. +This distribution contain the spong source, documentation, and gif images. +

SUPPORT

+There are two mailings setup for Spong: spong-users and spong-announce. +

+spong-users is for general discussions or getting help for Spong. You can +subscribe by sending a message to spong-users-request@lists.sourceforge.net +with the work subscribe in the message. Or be visiting the mailing lists +home page at http://lists.sourceforge.net/mailman/listinfo/spong-users. +

+spong-announce +is a low-volume mailing which will be used for announcements and news concerning +Spong. It is moderated, but feel free to submit any pertinent items. You can +subscribe by sending a message to spong-announce-request@lists.sourceforge.net +with the work subscribe in the message. Or be visiting the mailing lists +home page at http://lists.sourceforge.net/mailman/listinfo/spong-announce. +

DEPENDENCES

+Perl v5.004 or greater is all that is required to set up Spong. A web server +where you can install a CGI program, and a web browser that can display +tables and frames are required for use of the web interface to Spong. If +you want to monitor DNS servers remotely, then you will need to install +the Net::DNS Perl module (available at CPAN). Spong will run fine without +this module, you just will not be able to monitor the DNS service. +

+These scripts should run on any Unix system (and to ``some'' degree +any environment where Perl is available). +

DOCUMENTATION

+Don't let the amount of documentation scare you, I still think Spong is +simple to setup and use. +

+The documentation is provided in perl POD format (the old Perl pod +format just didn't do all that I wanted). The installation process will create +HTML, text and man formatted versions of the documentation. The HTML +documentation can be located anywhere. It's cross-links should survive a move +intact. +

+There are four main documents that describe spong from different +perspectives. +

+
+FAQ +
+
+Frequently Asked Questions by users and their answers. +
+
+
+User-Guide +
+
+Geared towards the person who will be using the spong text or web based +clients. This is the documentation that will be seen when the user clicks +on the Help button provided in www-spong. +
+
+
+Administrator's Guide +
+
+Written for the person who will be installing spong, and setting up the +various configuration files. This provides a step by step installation +process and gives some suggestions on things Spong can do that you might +not have thought of. +
+
+
+Developer's Guide +
+
+Written for the person who wants to have Spong look differently, or what +to add some new feature in their version of spong, or wants to incorporate +spong output in other programs. This details the Spong internals, and +describes the various protocols that are used. +
+

+There are also specific "man" pages for each program and configuration +file which provide detailed explanations of each option, command line argument, +etc... Finally, if you are in a pinch, the code is readable enough (and +well commented) to provide some help as well. +

+I hopefully have provided enough documentation that the only email +I get are suggestions for new features and bug reports - but if you are +stuck, feel free to send me email and I will respond if I can. +

FILES

+Here is a description of the directories and files that come in this package +prior to installation. More specific descriptions of each file are available +in the various documentation that comes with spong. +

+config: +

+spong.conf distributed config file +

+spong.conf.<os> os specific config changes +

+spong.hosts host/service config file +

+spong.groups group config file +

+src: +

+spong.pl text based spong display client +

+spong-client.pl collects/reports cpu,disk,etc info +

+spong-network.pl collects/reports network service info +

+spong-server.pl listens for/saves spong status updates +

+spong-message.pl alerts humans there's a problem +

+spong-ack.pl text based acknowledgement program +

+www-spong.pl web based spong display client +

+www-spong-ack.pl web based acknowledgement program +

+docs: +

+<*>.html documentation for the above files +

+gifs: various icons used by www-spong +

LICENSING

+Like Perl, Spong may be copied only under the terms of either the Artistic +License or the GNU General Public License, which may be found in the Perl 5.0 +source kit. If either file is not available to you, send email to +<sjohnson@monsters.org, and I will mail you a copy. +

CHANGES

+The list of changes for the latest version of Spong can be found +at http://spong.sourceforge.net/documentation/CHANGES. +

Version 2.7 +

+Enhanced error logging to log file, syslog, and stderr added to all programs. +Command line paramters are now handle by Getopts::Long perl module to +consistancy. Debugging output levels can now be specifie in all programs. Date +and Time displays are now configurable using strftime() format strings. +

+Spong Server network code changed from single threaded to forking. Status +information for for entries in the History file are now stored. Command line +program for sending status message in scripts or programs added. +

+Change to the Web interface include displaying Hosts grouped by Host Group, +option static Title frame, configuration toolbars added to multiple displays. +The Spong Network checking program now has a more agressive, and configurable, +error checking routine. Message templates has been added into the Spong Message +notification program. And an alpha WAP interface has been added. +

Version 2.6 +

+Notification rules enhanced with matching and excluding by host groups. +Added delayed and repeat notifications. Module Plugin mechanisms added +to spong-client, spong-network, spong-server, and spong-message programs. +Programs now automatic background themselves. Event duration added to spong-server +database. NTP and SSH checks added to spong-network. +

Version 2.5 +

+First release by Stephen L Johnson. Rules based notifications added, +a limited Big Brother Server emulation was to allow Big Bother Clients +to be used. A new log monitoring routine which tracks last position read. +Enhanced network checks to eliminate momentary network problems. +

Version 2.0 +

+A OO redesign of the spong-server and display programs, added acknowledgments +and group support, added a text based interface, made www interface more +extensible. +

Version 1.1 +

+Primarily a bug fix release with a few minor features (dns,http config,multiple +interfaces) added. +

Version 1.0 +

+Initial public release, mostly based on Big Brother package from Sean MacGuire. +

ACKNOWLEDGMENTS

By Ed Hill

+Many ideas (and some code) came from two similar packages. We have used +a program call "Pong" here at The University of Iowa for about a year. +Pong was written by Helen Harrison at SAS Institute and a paper on it was +presented at the Usenix LISA conference. Pong would allow us to do simple +monitoring of systems (via ping) and would report machine status via a +web page. The name of this package (Son of PONG, but pronounced as its +spelled "spong") is an obvious rip off... +

+Originally, the main concepts and design came from Big Brother written by Sean +MacGuire. That package was written in C and sh scripts which I ``ported'' to +Perl, making many changes along the way (like adding more information to the +messages going from the client to the server, adding history, changing the way +that information is displayed, added some configuration options, etc.). +

+There didn't seem to be any interest in my perl code from the author +of BB, so I've changed the name so there would be any confusion between +this package and its inspiration. +

+I'd also like to thank the many people who have contributed patches +and comments, and where willing to try out spong and help me work out a +few of the early problems. +

by Stephen L Johnson

+I first found Big Brother and liked what it did. But I was put as a bit by +it being written in C and shell scripts. While perusing the Big Brother mailing +lists archives I ran across references to Spong, and it being written in Perl. +This was Spong 1.1 +

+I tried it out but there were some stability problems. So I reluctantly dropped +Spong in favor of Big Brother. I didn't like some of the limitations of +Big Brother, so I started hacking on the source code. To me it was akin to +writing in assembler and getting a tooth pulled. I don't like either one. +

+Fortunately I found a link to Ed Hill's installation of Spong 2.1 at the +University of Iowa. I feel in love with Spong all over again. I asked Ed Hill +if I could have Spong 2.1. He sent me the distribution and I started evaluating +it again. +

+Spong 2.1 was a big improvement over Spong 1.1 in terms of stability +and features. I rolled the changes that I made to Big Brother into Spong 2.1 +and I have been changing things ever since. +

+Ed Hill had stopped development of Spong and I was spending so much time on +Spong. I asked Ed if I could take over development of Spong. He gave his +blessing and the torch was passed in October of 1999. +

+I would like to thank Ed Hill for creating Spong and allowing me to take up the +development touch. The current Spong user and development community is small +but growing. There are still a lot of rough edges to need to be smoothed. I +would like to thank them for their patient in allowing me to whip the Spong +distribution into shape and helping me work out the numerous installation +problems. +

BUGS

Known Problems in v2.6

+Here are a list of problems, and possible fixes that have been reported +for version 2.8. I will update this section as bugs come in (if there are +any 8-). These fixes will all be included in the next release of spong, +but if you can't wait - here are some suggestions. +

Memory leak in spong-network on RedHat 6.0 +: +spong-network has a memory leak when running on a Linux system and gligc 2.1.1. +The program memory core size grows after each check cycle. The fix is to +upgrade the glibc from version 2.1.1 to version 2.1.2. +

AUTHOR

+Ported by: +

+Ed Hill <ed-hill@uiowa.edu> +Internet Software Developer at The University of Iowa http://www.uiowa.edu/ +

+Currently maintained by: +

+Stephen L Johnson <sjohnson@monsters.org> +

+Please feel free to send me bug reports, patches, suggestions, or comments. +

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:02 2002 + + + diff --git a/www/docs/spong-message-mod-template.html b/www/docs/spong-message-mod-template.html new file mode 100755 index 0000000..2990e0c --- /dev/null +++ b/www/docs/spong-message-mod-template.html @@ -0,0 +1,32 @@ + + + + + + +spong-message-mod-template + + + + + +

Next:
spong-network

Previous:
spong-message

[Table of Contents]

[Index]

spong-message-mod-template

NAME +
DESCRIPTION +

NAME

+spong-message-mod-template - how to build spong message template +

DESCRIPTION

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:03 2002 + + + diff --git a/www/docs/spong-message.html b/www/docs/spong-message.html new file mode 100755 index 0000000..23194d8 --- /dev/null +++ b/www/docs/spong-message.html @@ -0,0 +1,380 @@ + + + + + + +spong-message + + + + + +

Next:
spong-message-mod-template

Previous:
spong-intro

[Table of Contents]

[Index]

spong-message

NAME +
SYNOPSIS +
DESCRIPTION +
- Options +
- Theory of Operation +
- Message Templates +
- Messaging Modules +
+
CONFIGURATION +
- Configuration Files +
- Configuration Variables +
+
FILES +
EXAMPLES +
DEPENDENCIE/h1 +
BUGS +
SEE ALSO +
AUTHOR +
HISTORY +

NAME

+spong-message - send out alerts when there is a problem +

SYNOPSIS

+spong-message [--debug] [--file filename | --message "detailed +message text"] color host service time message +

+spong-message [--debug] --color|--status color --host +hostname --service service --time time --summary "summary +message text" [--file filename | --message "detailed message +text"] +

DESCRIPTION

+This program is called by the the spong-server manpage to send out alerts. The +the spong-server manpage only makes a quick determination for send out alerts. It's only +criteria is a change in status of a service. The spong-message make a more +thorough determination of transmitting the alerts according to the message +rules defined in the the spong.message manpage configuration file. spong-message +also has throttling mechanisms to prevent an excessive number of messages from +being send within a short amount of time. +

Options

--debug +: +Enables the printing of detailed debugging lines. Can be used in conjunction +with --test to test new messaging rules. +
--color|--status color +: +Specified the status color of the event being reported. color can be +green, yellow or red. +
--host hostname +: +The hostname of the server that is being reported on. +
--service service +: +The name of the service that is being reported on. +
--time time +: +The time of the event being reported in epoch format (i.e. time()). +
--summary "summary text" +: +This is the summary message field of the event being reported on. +
--file filename +: +The name of a file to read the detailed message text from. If the filename is '-', the text is read from stdin. +
--message "message text" +: +Detailed message text of the event being reported. +

+The following parameters can be specified on the command line with the +accompanying command line parameters. +

color +: +the status color of the message (red, yellow, or green) +
host +: +the hostname being of the alert +
service +: +the name of the service of the alert +
time +: +the date/time (in time() format) of the problem +
message +: +a summary line of the problem +

Theory of Operation

+When spong-message is called, the information passed in the arguments is run +through a list of rules which determine who is contacted, when they are +contacted and how often. The information is also run through a number of checks +to determine if the message should be sent. +

+A small database in the $SPONGTMP directory is kept +so that spong-message can keep track how many pages have been sent, when +was the last page sent, etc. These checks help to direct problems to the +correct people, and also help to throttle messages when there are wide-spread +problems (such as a networking outage). +

+If you are going to be performing maintenance on a machine, or have standard +down time for a machine, you can specify that down time in the spong.hosts file +using the down attribute in a +%HOSTS variable. If a problem is reported during the +time indicated, spong-message will not send any messages. +

+spong-message also checks for any acknowledgements active for +a machine. If there an active acknowledgement found for a machine and service, +no messages will be sent. +

+spong-message uses the %HUMANS entries defined in +the contacts attributes of the messaging rules of +the spong.message manpage to determine who is to be contacted. A list of contacts is +generated from all of the message rules that are matched. (See the +the spong.message manpage and the spong.hosts manpage documentation for information on the file +formats.) +

Message Templates

+Notification messages are formatted by message templates in the %TEMPLATES +configuration variable in the spong.message file. The 'DEFAULT' template +is use is no other template is found. Templates override can be defined for any +contact, message module, or a combination of the two. See +the section on MESSAGE TEMPLATES in the spong.message manpage for information on the file format. +

Messaging Modules

+spong-message alerts people via the messaging modules that are installed. +New messaging functions can be easily created. See the Message Modules section in the Developer Guide. +

CONFIGURATION

Configuration Files

spong.hosts +: +spong.hosts defined attributes for two things of important to <spong-message> +1) the hosts that Spong is monitoring (%HOSTS), and 2) the contacts that +are responsible for the various hosts and how to contact them (%HUMANS). +
+See the spong.hosts manpage for a full description of all of the file formats. +
+
spong.message +: +This file hold the rules that determine who is to be contacted, when and how +often. There are some of the important configuration variables in the +spong.message file 1) how the messaging rules are to be scanned +($RULES_MATCH), 2) the messaging rules +($MESSAGING_RULES), 3) how to format the +messages being sent (%TEMPLATES). +

Configuration Variables

+From spong.hosts: +

%HUMANS +

+The %HUMANS configuration variable hold all of possible message recipients +(the humans) and the information necessary on how to contact them. Each +human contact can be a person, a group of people, or really anything you +want. +

+Each human that is defined should have name attribute associated +with it. name is the name or description of the contact. +

+To send out any notifications at least messaging attribute must be +define for the human. A messaging attribute consists of a message module +name as a key and contact information as a value. See the section on EXAMPLES elsewhere in this document for a +detailed %HUMANS example. +

%HOSTS +

+The %HOSTS configuration variables can hold a list of regularly scheduled +maintenance periods (down) for each host. Any alerts that are generated +during a maintenance period will be silently discarded. +

+From spong.message: +

$RULES_MATCH +: +$RULES_MATCH determines how the rules in +$MESSAGING_RULES are scanned. If it is +FIRST_MATCH the rules will be scanned until the first rule that matches the +messaging criteria. A value of ALL means that all of the rules are scan with +the contacts of all matching rules being adding into the list of contacts to +notify. If the value is OLD, then spong-message will fall back to the +messaging code used in Spong versions 2.0 - 2.1 for compatibility. +
$MESSAGING_RULES +: +$MESSAGING_RULES contains the rules that +how, who and how often contacts are notified. See +$MESSAGING_RULES for the full rules syntax. +
%TEMPLATES +: +%TEMPLATES determined how notification message are formatted. A template +format consists a subject and message template strings. Both strings are not +required as some message module will not require a subject or a body. See +$MESSAGING_RULES for the full rules syntax. +

+From spong.conf: +

$SEND_MESSAGE +: +$SEND_MESSAGE +defines when spong-message is called by spong-server. It is not really +specific to spong-message, but I think it is useful to describe its behavior +here. 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 every time a service or service reports 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. +
$MESSAGES_PER_HOUR +: +$MESSAGES_PER_HOUR 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 +: +$IDENT_MESSAGES_PER_HOUR is the +maximum number of identical messages that are sent to the same person in an +hour. The default value is 3. +

FILES

+spong.conf, +spong.hosts, +$SPONGTMP/message-db, +spong.message +

EXAMPLES

+Here are some examples to show you possible configurations. +

spong.hosts +

+   %HUMANS = (
+      'unix-staff' => { 'name'   => 'Midrange On-call Staff',
+                        'email'  => 'its-unix@school.edu'
+                       },
+
+      'georgew'    => { 'name'   => 'George Wilson',
+                        'email'  => 'georgew@school.edu',
+                        'skytel' => '1234567' }, 
+   );
+
+   %HOSTS = (
+
+     'grad.cs.school.edu' =>      { services => 'ftp smtp http',
+                                   'down'   => ["*:05:30-06:30",
+                                                 "0:00:00-04:00" ] },
+
+     'www.school.edu' =>         { services => 'ftp smtp http' },
+
+   );
+

spong.message +

+    $RULES_MATCH = 'FIRST-MATCH';
+
+    $MESSAGING_RULES = [
+
+       { hosts => [ 'gard.cs.school.edu' ],
+         contacts => [ 'unix-staff'],
+         exclude_colors => ['green','yellow'],
+       },
+
+       { hosts => ['www.school.edu'],
+         contacts => [ 'georgew:email',
+                       { rcpt=>'georgew:skytel', repeat=>900, }, ]
+       },
+
+    ];
+
+    %TEMPLATES = (
+
+      'DEFAULT' => { subject => 'spong - !!COLOR!! !!HOST!! !!SERVICE!!',
+                     body    =>
+    '!!DATETIME!!
+    !!COLOR!! !!HOST!! !!SERVICE!!
+    !!SUMMARY!!',
+                   },
+
+    'email'  => { subject => 'spong - !!COLOR!! !!HOST!! !!SERVICE!!',
+                  body    =>
+    'Host !!HOST!! service has been reported !!COLOR!!.
+    Summary: !!SUMMARY!!
+
+    Spong Web Page:      !!WWWSPONG!!
+    Service Detail Page: !!WWWSPONG!!/service/!!HOST!!/!!SERVICE!!
+
+    Status event details:
+    !!DETAILED!!
+    ',
+              },
+    );
+

DEPENDENCIE/h1

+ +Perl v5.003 or greater is required. +

+To receive pages, you currently must have a pager that can be contacted +electronically (via email or web interface). +

BUGS

+No know bugs. +

AUTHOR

+Ed Hill <ed-hill@uiowa.edu>, Unix System Administrator, The University of +Iowa +

+Stephen L Johnson <sjohnson@monsters.org> +

HISTORY

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:03 2002 + + + diff --git a/www/docs/spong-network-mod-template.html b/www/docs/spong-network-mod-template.html new file mode 100755 index 0000000..d5cf7bd --- /dev/null +++ b/www/docs/spong-network-mod-template.html @@ -0,0 +1,129 @@ + + + + + + +spong-network-mod-template + + + + + +

Next:
spong-server

Previous:
spong-network

[Table of Contents]

[Index]

spong-network-mod-template

NAME +
DESCRIPTION +
SEE ALSO +
AUTHOR +
HISTORY +

NAME

+spong-network-mod-template - A sample spong-network check module +

DESCRIPTION

+This document describes a sample plug-in module for the spong-network +program. Any modules that you create can be custom network checks, or they +can be replacements for the core Spong modules. +

+This template assumes that you are creating a network check called +'dns'. The name of the file created should be 'check_dns'. The file name +should always be 'check_' plus the registry name (e.g. for the foo check, +the registry name is 'foo' and the file name is 'check_foo'. +

+The line that has the assignment to $PLUGINS{'registry-name'} is the +key to the registry mechanism. It's what ties the registry name to the +the checking function. +

+The registry name does not always have to match up to the service name as in +the case of our module 'dns'. If you where creating a new and improved function +to ping and traceroute, you could create a module called 'ping_trace'. You +would use the registry name 'ping_trace', but you would use the service name +'ping' in the &main::status() function when reporting your information +back to the server. +

+check_dns:
+
+  # Register the routine with the plugin registry
+  $PLUGINS{'dns'} = \&check_dns;
+
+  # Check to see if they have the Net::DNS module installed, and if they do we
+  # can then do DNS queries, and see if DNS servers are alive.
+
+  eval "require Net::DNS;";
+  if( ! $@ ) { $dns = 1; } else { $dns = 0; }
+
+  # This check will (if the Net::DNS module is available) connect to a DNS
+  # server and ask that server to resolve it's own name. If it can do that,
+  # then we assume it is ok - If it can't then something is wrong.
+
+  sub check_dns {
+      my( $host ) = @_;
+      my( $color, $summary, $message ) = ( "green", "", "" );
+
+      if( ! $dns ) {
+         $summary = "can't do DNS lookups, Net::DNS not installed";
+         &main::debug( "dns - $host - $color, $summary" );
+         return ( "yellow", $summary,
+         "In order to do DNS queries you must install the Net::DNS " .
+         "Perl module.\nYou can find the module at your nearest CPAN " .
+         "archive or http://www.perl.com/CPAN/\n" )
+      }
+
+      my $resolver = new Net::DNS::Resolver;
+      $resolver->nameservers( $host );
+      $resolver->retrans(2);
+      $resolver->retry(1);
+      $resolver->recurse(0);
+      my $q = $resolver->search( $host, "A" );
+
+      if( defined $q && defined $q->answer && defined (($q->answer)[0]) ) {
+          $color = "green";
+          $summary = "dns ok";
+      } else {
+         $color = "red";
+         $summary = "can't resolve $host";
+         $message = "can't resolve $host\n";
+      }
+
+      &main::debug( "dns - $host - $color, $summary" );
+      return( $color, $summary, $message );
+  }
+
+  # I'm included perl code, I need this line.
+  1;
+

+Please note the final line. It is always required for a module file. +

AUTHOR

+Stephen L Johnson <sjohnson@monsters.org> +

HISTORY

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:04 2002 + + + diff --git a/www/docs/spong-network.html b/www/docs/spong-network.html new file mode 100755 index 0000000..4c5a846 --- /dev/null +++ b/www/docs/spong-network.html @@ -0,0 +1,246 @@ + + + + + + +spong-network + + + + + +

Next:
spong-network-mod-template

Previous:
spong-message-mod-template

[Table of Contents]

[Index]

spong-network

NAME +
SYNOPSIS +
DESCRIPTION +
+
CONFIGURATION +
- Configuration Files +
- Configuration Variables +
+
FILES +
DEPENDENCIES +
BUGS +
SEE ALSO +
AUTHOR +
HISTORY +

NAME

+spong-network - report network service information to spong server. +

SYNOPSIS

+spong-network [--debug n] [--kill|--restart|--nosleep|--refresh]
[config_file] +

DESCRIPTION

+This checks network connectivity and network service availability to various +machines you want to monitor. It reports the status of the network services +that it monitors to the spong server. Everything happens again after sleeping +for a time period you have defined in your configuration file. This program +typically runs on your spong server machine (although it can be run on any host +- although I would suggest one with good network connectivity). +

+The program checks a series of network services that are configured separately +for each host. spong-network also can be very aggressive in checking for +network service that are down. You can configure multiple rechecks to guard +against transitional failures. +

Running the program

+You should start this program in your system startup file, and it should be +running constantly. If no parameters are specified, spong-network forks +and detaches itself to run as a daemon. +

+If you provide the --restart flag, a signal will be sent to the spong-network +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 flag causes the program to cycle through all +of the checks once then exit. These flags can be used to run spong-client as a +cron job (depreciated), but it recommended that you run the program +continuously. +

Format of update messages

+It sends a message for each check to the spong server and reports the +following: +

hostname (where is this report coming from)
+
service name ("disk", "cpu", "procs", "logs", "local")
+
color ("red", "yellow", "green")
+
a one line summary
+
a more detailed message providing additional detail.
+

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

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

+The more detailed message contains information such as the output of +the ping command from the check ping module or the data read after testing +a network service. +

Network Checks

+The check are actually a setup of modules that are called in series by +spong-network. Upon initialization, spong-network will load the all of +the modules that will be used from the LIBDIR/Spong/Network/plugins +directory. As each module is initialized, it registers itself with the plugins +registry (see the Developer Guide). +

+The list of network checks and the order the are performed that are performed +for a host are defined in the services attribute of the host's entry in the +%HOST variable. The ping service is appended by +default to all of the lists of services to be check for a host. If the +meta-service name of noping is defined for a host, the ping check will no be +done for the host. +

CONFIGURATION

Configuration Files

spong.conf +: +By default this reads the spong.conf 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. +
spong.conf.[hostname] +: +After reading the configuration file that you specify (or the default), +it then reads the spong.conf.[hostname] file where [hostname] 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. +
spong.hosts +: +spong-network reads all of the host that are to be check from the +%HOSTS variable in the the spong.hosts manpage file. The +list of services to be check for each host is already read from spong.hosts. +

Configuration Variables

+From spong.conf: +

$SPONGSLEEP, $SPONGSERVER, $SPONG_UPDATE_PORT +: +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 +
$SPONGSLEEP{'DEFAULT'}, $SPONGSLEEP{'spong-network'} +: +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 +$SPONGSLEEP{'DEFAULT'} value. If no value is then found, spong-client +fall back to using $SPONGSLEEP. +
$SPONGTMP +: +The directory that Spong programs use for temporary store and work files. It +should be different a directory than /tmp for operation and security reasons. +
$SPONG_LOG_FILE +: +If set to 1, spong-network will log errors to a log file in $SPONGTMP +named spong-network.log. +
$SPONG_LOG_SYSLOG +: +If set to 1, spong-network will log errors to the syslog using the +USER facility and the ERR priority. +

+From spong.hosts: +

%HOSTS +: +All of the host names defined in %HOSTS are the list of hosts that +spong-network will check. The services defined in the services attribute +are the list of services that will be check for each host. The ping service +is prepended to the list of services unless 'noping' is defined. +
+Another important attribute for a host is the +skip_network_checks flag. If this flag is +set for a host. The spong-network proram will skip the check for the host. +
+

FILES

+spong.conf, spong.conf.hostname, spong.hosts +

DEPENDENCIES

+Perl v5.005_03 or greater is required. +

BUGS

+The check_dns module uses the Net::DNS Perl module. On some systems the +Net::DNS module will fail and start reporting false DNS lookup failures. The +cause is unknown at present. This will cause dns check for all hosts to fail +and be reported as a critical status. The fix is to restart spong-network +(i.e. spong-network --restart ), +

+A work-around is to regularly do restart spong-network, such as from a +cron job. +

AUTHOR

+Ed Hill <ed-hill@uiowa.edu>, Unix System Administrator, The University of +Iowa +

+Stephen L Johnson <sjohnson@monsters.org> +

HISTORY

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:03 2002 + + + diff --git a/www/docs/spong-server-mod-template.html b/www/docs/spong-server-mod-template.html new file mode 100755 index 0000000..89771f3 --- /dev/null +++ b/www/docs/spong-server-mod-template.html @@ -0,0 +1,291 @@ + + + + + + +spong-server-mod-template + + + + + +

Next:
spong-status

Previous:
spong-server

[Table of Contents]

[Index]

spong-server-mod-template

NAME +
DESCRIPTION +
Message Formats +
- Status Message +
- Acknowledge Message +
- Delete Acknowledge Message +
- Special Fields +
+
Example Module +
SEE ALSO +
AUTHOR +
HISTORY +

NAME

+spong-server-mod-template - how to build a spong-server data modules +

DESCRIPTION

+The old data spong-server plugin modules are now deprecited in favor of predata +and postdata modules. Spong Server data modules will continue to be supported +for the future. But you are encouraged to convert any custom modules to the new +format, and update any old data plugin to their new pre- or post-data +equivalent. +

+The file name of the module must begin with 'predata_' or 'postdata_'. +'predata_' is for a predata module. The module will be called immediately after +an incoming message is received, but before normal processing. 'postdata_' is +for a postdata module. The module is called after the normal processing is done +for the message. +

+Modules are called in the order of their registry key in alphabetical order. +The registry key can be anything, but it should be consistent with the +module's name. And the registry must be unique among the other loaded +modules; otherwise, one module will overlay the other. +

+The line that has the assignment to $DATAFUNCS{'registry-name'} is the +key to the registry mechanism. It's what ties the registry name to the +your data module. +

Message Formats

+The fields of messages are passed to the module in the form of a Perl hash. +This hash is the only parameter passed to the module when it is called. +

Status Message

+This is the most common type of message received by the Spong Server. A status +message reports the current status of Spong Client and Spong Network +checks and tests. +

header +: +The field contains the first line of a status message. If consists the cmd, +host, color (aka status), time, and summary fields. +
message +: +This is the detailed status message field. It generally consists of multiple +lines of text. This field can be quite large. Upwards of a few K is nor +unusual. +
cmd +: +This is command field from the header. It will a contain a string with the +value of 'status'. +
host +: +This is hostname from the status message header field. It will contain the +name of the reporting host. if will contain a strings that will typically be +the fully qualified domain name of the host. It is the same of the hostname +given in the the spong.conf manpage configuation file. +
service +: +This is the service name from the message header field. It will contain a +string. It it the name of the service or resource that was tested. The service +names are the column names on the Web Status screens. +
color +: +This is the status color of the test being reported. It will contain a string consisting of one of these values: 'red', 'yellow', 'green', 'purple', 'clear'. The have a meaning of: red=critical, yellow=warning, green=normal, purple=old/stale data, clear=status unknown. +
time +: +This is the timestamp of the status as given by the rporting host. If will +consist of system time in epoch format (i.e. as reported by time() ). Epoch +date format is the number of seconds since a given epoch. Jan 1, 1970 12:00 AM +for UNIX based systems. +
duration +: +The field contains the current duration that the service has been in it's +current status (color). The time is given in seconds. +
summary +: +This is summary fields from the status message. It is a short summary of the +current status of the services being reported. It will be one line of test. Generally less then 40 characters (not guaranteed). +

Acknowledge Message

+Acknowledge messages are generate when an acknowledgement is created. This +message is fairly rare. +

header +: +The field contains the first line of a status message. If consists the cmd, +host, service, start_time, end_time, and user fields. +
message +: +This is an information/note field. It's typically used to give the reason for +the acknoloedgement. It generally consists of multiple lines of text. This +field can be quite large. +
cmd +: +This is command field from the header. It will a contain a string with the +value of 'ack'. +
host +: +This is hostname the acknoledgement that is being created. It will contain a +strings that will typically be the fully qualified domain name of the host. It +is the same of the hostname given in the the spong.conf manpage configuation file. +
service +: +This field is the service(s) the acknowledgement is being created for. It will +contain a string. It wll be a command seperated list of service names or the +strings 'all' to represent all services. The service names are the column +names on the Web Status screens. +
start_time +: +This is the date/time of the start of the acknowledgement period. It will +consist of system time in epoch format (i.e. as reported by time() ). Epoch +date format is the number of seconds since a given epoch. Jan 1, 1970 12:00 AM +for UNIX based systems. +
end_time +: +This is the date/time of the end of the acknowledgement period. It will +consist of system time in epoch format (i.e. as reported by time() ). Epoch +date format is the number of seconds since a given epoch. Jan 1, 1970 12:00 AM +for UNIX based systems. +
user +: +This field gives and indication of the user who is creating the acknowledgment. +This is just an informational field. It will consist of a string that contains +an e-mail address (username@hostname). This is not a hard and fast requirement. +=back +

Delete Acknowledge Message

+Delete Acknowledge messages are sent to delete an existing acknowledgement. +This message is fairly rare. +

header +: +The field contains the first line of a status message. If consists the cmd, +host, service, and end_time fields. +
cmd +: +This is command field from the header. It will a contain a string with the +value of 'ack'. +
host +: +This is hostname of the acknoledgement that was created. It will contain a +strings that will typically be the fully qualified domain name of the host. It +is the same of the hostname given in the the spong.conf manpage configuation file. +
service +: +This field is the service(s) the acknowledgement is being created for. It will +contain a string. It wll be a command seperated list of service names or the +strings 'all' to represent all services. The service names are the column +names on the Web Status screens. +
end_time +: +This is the date/time of the end of the acknowledgement period. It will +consist of system time in epoch format (i.e. as reported by time() ). Epoch +date format is the number of seconds since a given epoch. Jan 1, 1970 12:00 AM +for UNIX based systems. +

Special Fields

+Predata modules add a special field/flag to the message hash before returning. +The presence of this flag field will tell Spong Server to drop the message. The messge will be dropped and forgotten. Normal processing will not be done, and +postdata modules will not be called. +

drop_msg +: +This field can be added to the passed messge field hash. If must be added with +a none zero (0) value. See the example module below for it usage. +

Example Module

+This template will be a simple example that will redirect disk status updates +to an alternate Spong Server for processing. We only want the Database Server +hosts dbserv*.example.com. And we will tell the Spong Server to drop the +message to let the alternate Spong Server to handle it. +

+predata_redirect:
+
+  # Register the routine with the plugin registry
+  $DATAFUNCS{'redirect'} = \&predata_redirect;
+
+  use Spong::Status;  # We'll being this module to send the message
+
+  $ALTSERVER = 'spong-disk.example.com:19980';
+
+  sub predata_redirect {
+     my( $msg ) = @_;
+

+     # Return is not status message for disk for dbserv* 
+     return if ( $msg->{'cmd'} ne 'status'  ||
+                 $msg->{'service'} ne 'disk' ||
+                 $msg->{'host'} !~ m/dbserv.*\.example\.com/ );
+

+    # Send the message to the alternate Spong Disk server
+    Spong::Status($ALTSERV, 1998, $msg->{'header'} . "\n"
+                                  $msg->{'message'} );
+

+   # And tell the server to drop the message and don't process it
+   $msg->{'drop_msg'} = 1;
+
+   return;
+
+  }
+
+  # I'm included perl code, I need this line.
+  1;
+

+----- +

+Please note the final line. It is always required for a module file. +

+You should use the &main::error() function to log any error encountered +in your module. The &main::error() function is used to write output +whenever something interesting happens in your module. +

+Any configuration variables needed for your data modules can be put into the +Global section of your module as shown above. Of it can be added into the +spong.conf or spong.conf.<host> configuration files. +Configuration variables for your module should be named to match them up +with the name of your customized check. +

AUTHOR

+Stephen L Johnson <sjohnson@monsters.org> +

HISTORY

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:05 2002 + + + diff --git a/www/docs/spong-server.html b/www/docs/spong-server.html new file mode 100755 index 0000000..54349a5 --- /dev/null +++ b/www/docs/spong-server.html @@ -0,0 +1,328 @@ + + + + + + +spong-server + + + + + +

Next:
spong-server-mod-template

Previous:
spong-network-mod-template

[Table of Contents]

[Index]

spong-server

NAME +
SYNOPSIS +
DESCRIPTION +
+
CONFIGURATION +
- Configuration Files +
+
FILES +
DEPENDENCIES +
BUGS +
SEE ALSO +
AUTHOR +
HISTORY +

NAME

+spong-server - save status information reported by spong programs +

SYNOPSIS

+spong-server [--debug n] [--kill|--restart] [---test]
[config_file] +

DESCRIPTION

+The spong-server is the central core program of Spong. The program received +status reports from various spong clients (specifically spong-network and +various spong-client program running). If the message is worth notifying +someone about, it calls the spong-message program. The status messages +messages are stored into an internal database with significant changes being +logged into a history event log. Queries from spong interface programs (like +spong and www-spong) seeking to display the data in the spong-server +database. +

Running the program

+You should start this program in you system startup file, and it should be +running constantly. If no parameters are provided, spong-server will +fork and detach itself from the console to run as a daemon. +

+If you provide the --debug n flag then debugging information will be +printed to stderr. The n is an integer from 1 to 9. A higher number means +more verbosity in the debugging output. +

+If you provide the --restart flag, a signal will be sent to the +spong-server process that is currently running. It will release reload it's +configuration and restart. If the --kill flag if provided, a signal will +be sent to the running spong-server process causing it to exit. +

+The --test parameter has no effect in the spong-server program itself. +If specified on the comment line, the --test parameter will be passed +to the spong-message program when it is called. The <--test> paramter +will cause spong-message to skip the actual send of notifications. +

+An alternate configuration file can be specified on the command line. This +file will be read instead of the default spong.conf configuration file. +

Theory of Operation

+The spong-server has a main process that spawns a number of child processes +to handle all of the work. There are a query process which handles queries into +the Spong database, an update process which handles Spong formatted update +messages (see the section on SPONG PROTOCOL in the developer-guide manpage), a BBSERVER +update process which handled Big Brother client update messages, and possibly +other process are more feature are added in the future. The main process +monitors each of the child processes. It will restart any child process that +dies for any reason. +

+Each time a connection comes in, the child process is forks off to handle the +the above tasks. The main child process goes back to waiting for more +connections. +

Data Modules

+The spong-server has a plug-in module facility similar to the other +Spong programs. One or more modules can be installed in the +LIBDIR/Spong/plugins/ directory. The modules are loaded are run-time by +spong-server. As each module is initialized is registers itself with +the plug-ins registry. +

+Each module is called in turn after all of the normal processing is done for +incoming status messages. This allows you access to data of a status message +that will eventually be discarded. Data modules can do virtually anything that +you desire with the incoming data. The data can be written to a log or +database or feed to another application for further filter or processing. +

+Two sample data modules are located in the contrib/plugins/spong-server +directory of the Spong distribution. The two modules (data_rrd_disk and +data_rrd_la work in conjunction with a software package named RRD Tool to +log disk and cpu information into Round Robin Databases. The modules are +included as examples. They are not of must use by themselves. See the +Spong-RRD package (http://spong.sourceforge.net/downloads.html) for a +complete package that utilizes data modules. +

Big Brother (BBSERVER) Emulation

+The Spong Server has a partial Big Brother ( http://bb4.com/ ) server emulation +mode. This also Big Brother Clients to be used with Spong. The emulation mode +is enabled by configuring the $SPONG_BB_UPDATE_PORT parameter in the +spong.conf configuration file. +

+Note: The Spong BBSERVER Emulation mode only supports status messages from +Big Brother Client programs. Alert messages are not supported and are silently +ignored by the spong-server. +

TCP Wrappers

+The spong-server can use the TCP Wrappers Library. The TCP Wrappers Library +implements a rules-based access control languguage. This allows incoming +connection to be validated by host names and/or IP addresses. +

+To use TCP Wrappers, the libwrap.a library and the Authen::Libwrap Perl module +must be installed. The Authen::Libwrap module be found in the Comprehensive +Perl Archive Network (CPAN). See http://cpan.org/. +

+The names for the various spong-server services are as follows: +

+
+spong-update: Status message update service +
+
+
+spong-bb-update: Big Brother Server Emulation service +
+
+
+spong-query: Spong Database query service +
+

CONFIGURATION

Configuration Files

spong.conf +: +By default this reads the spong.conf 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. +
spong.conf.[hostname] +: +After reading the configuration file that you specify (or the default), +it then reads the spong.conf.[hostname] file where [hostname] 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. +
spong.hosts +: +spong-server reads all of the host that are defined in the +%HOSTS variable in the the spong.hosts manpage file. +spong-server uses this list of servers to validate incoming status and +control messages. And the list is used in format of database queries. +
spong.groups +: +The the spong.groups manpage file defines groups of hosts. spong-server uses these +host groups to filter and format the data returned in database queries. +

+From spong.conf: +

+Yes there are a lot of variables. But all of the variables have defined +default values. Most of these variables are used customizing the client +web and text interfaces. +

$SPONG_UPDATE_PORT +: +This variable defines the port that the Spong update process listens on. If +This variable is not defined the Spong update process will not be started. +The default value is 1998. +
$SPONG_UPDATE_PORT +: +This variable defines the port that the Spong query process listens on. If +this variable is not defined the Spong query process will not be started. The +default value is 1999. +
$SPONG_BB_UPDATE_PORT +: +This variable defines the port that the Big Brother BBSERVER emulation +process listens on. If this variable is not defined the Big Brother BBSERVER +emulation process will not be started. The default value is 1984. +
$SPONGSLEEP (Depreciated) +: +This variable is used by spong-server to determine how old a service +status can be before it is considered stale. It's status will be reported +as 'purple'. The exact time to live a message is 2 * $SPONGSLEEP. (This +variable is depreciated in favor of the new $SPONGSLEEP{} variables.) +
$SPONGSLEEP{'DEFAULT'}, $SPONGSLEEP{'spong-server'} +: +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 +$SPONGSLEEP{'DEFAULT'} value. If no value is then found, spong-client +fall back to using $SPONGSLEEP. +
$SPONGDB +: +This defined the directory where the Spong database will be stored. Each host +will have a subdirectory in this directory which is named for the host. +
$SPONGTMP +: +The directory that Spong programs use for temporary store and work files. It +should be different a directory than /tmp for operation and security reasons. +
$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. +
$SPONG_LOG_FILE +: +If set to 1, spong-network will log errors to a log file in $SPONGTMP +named spong-network.log. +
$SPONG_LOG_SYSLOG +: +If set to 1, spong-network will log errors to the syslog using the +USER facility and the ERR priority. +
$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 +spong-server will terminated the connection. This action can be disables +by setting the variable to zero (0). +
$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. If the host has a 'display_name' attribute, it will +be used in preference to the FQDN names. +
$HISTORY_FQDN +: +Set this varirable to 1 to display teh fully qualified domain name (FQDN) of +hosts in History displays display clients. Otherwise only the first element of +the FQDN will be displayed. If the host has a 'display_name' attribute, it will +be used in preference to the FQDN names. +

+From spong.hosts: +

%HOSTS +: +All of the host names defined in %HOSTS are the list of hosts that +spong-server will accept status messages for. Any status message for an +unknown host will be logged as an error and discarded. +

+From spong.groups: +

%GROUPS +: +The host groups that are defined in this variable are used to filter and +format data queries of the Spong database. +

FILES

+spong.conf, spong.conf.hostname, spong.hosts, spong.groups +

DEPENDENCIES

+Perl v5.005_03 or greater is required. +

BUGS

+No know bugs. +

AUTHOR

+Ed Hill <ed-hill@uiowa.edu>, Unix System Administrator, The University of +Iowa +

+Stephen L Johnson <sjohnson@monsters.org> +

HISTORY

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:04 2002 + + + diff --git a/www/docs/spong-status.html b/www/docs/spong-status.html new file mode 100644 index 0000000..d2fb879 --- /dev/null +++ b/www/docs/spong-status.html @@ -0,0 +1,147 @@ + + + + + + +spong-status + + + + + +

Next:
spong.conf

Previous:
spong-server-mod-template

[Table of Contents]

[Index]

spong-status

NAME +
SYNOPSIS +
DESCRIPTION +
OPTIONS +
CONFIGURATION +
- Configuration Files +
- Configuration Variables +
+
FILES +
EXAMPLES +
DEPENDENCIES +
BUGS +
SEE ALSO +
AUTHOR +
HISTORY +

NAME

+spong-status - send various type of messages to a spong-server +

SYNOPSIS

+ spong-status [--help]
+ spong-status [--ttl #] (--file name | --message "message text") CMD HOST
+              SERVICE COLOR "SUMMARY TEXT"
+ spong-status [--cmd cmd] --host name --service name --color color 
+              --summary text (--message text | -f filename) 
+              [--ttl seconds]
+

DESCRIPTION

+This program allows you to create your own extern spong client programs or +integrate existing monitoring program or scripts in Spong. spong-status +hides all of the details of the Spong Client/Server communication protocol. +

OPTIONS

--help +: +Print the help text +
--cmd status|page +: +Command type being sent to spong-server. Defaults to 'status'. +
--host NAME +: +Name of the host being reported. +
--service NAME +: +Name of the service being reported. +
--color <COLOR> +: +Status color being reported. COLOR may be ``green'', ``yellow'', or ``red''. +
--summary TEXT +: +Summary text to be reported. +
+
--ttl SECONDS +: +Time to live of status report in seconds. +
--message TEXT +: +Detailed message text being reported. +
--file FILENAME +: +Detailed message info read from file FILENAME. If FILENAME is '-', text is +read from stdin. +

CONFIGURATION

Configuration Files

+spong-cleanup reads the standard spong.conf and spong.conf.<host> +configuration files. +

Configuration Variables

$SPONGSERVER +: +The host that at least the the spong-server manpage and the spong-message manpage +programs are running on. Typically the the spong-network manpage program runs on that +host as well. +
$SPONG_UPDATE_PORT +: +This variable defines the port that the the spong-server manpage update process listens +on. If this variable is not defined on the $SPONGSERVER host, the +the spong-server manpage update process will not be started. The default value is 1998. +

FILES

+SPONGHOME/etc/spong.conf, SPONGHOME/etc/spong.conf.<host> +

EXAMPLES

+  spong-status --cmd status --host www.my-inc.com --service fping --color yellow
+            --summary "Host contacted. Response time more then 30 ms"
+            --file /tmp/fping.out
+
+  spong-status --ttl 86400 --message "Backup failed for /usr,/var" page
+            www.my-inc.com red backup "Backup failed"
+

DEPENDENCIES

+Perl v5.005_03 or greater is required. +

BUGS

+No know bugs. +

AUTHOR

+Stephen L Johnson <sjohnson@monsters.org> +

HISTORY

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:05 2002 + + + diff --git a/www/docs/spong.conf.html b/www/docs/spong.conf.html new file mode 100644 index 0000000..af912dc --- /dev/null +++ b/www/docs/spong.conf.html @@ -0,0 +1,429 @@ + + + + + + +spong.conf + + + + + +

Next:
spong.groups

Previous:
spong-status

[Table of Contents]

[Index]

spong.conf

NAME +
DESCRIPTION +
- All programs +
- spong-server +
- www-spong +
- www-spong-ack +
- spong-cleanup +
- spong-client +
- spong-message +
- OS SPECIFIC VARIABLES +
+
FILES +
SEE ALSO +
AUTHOR +
HISTORY +

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 spong.conf.<hostname> file ) gets +imported by each of the spong programs +

+The variables are grouped by the spong programs. Each section will list the +variables that are used in the program along with the meaning of the +variable to the program. +

All programs

+This sections deals with variables that are used by all of the Spong +programs. Any differences in how the programs use the variable will be detailed in the "Configuration Variables" section of the program's documentation. +

$SPONGSLEEP (Depreciated) +

+This variable holds the amount in time in seconds) that spong client programs +(i.e. spong-client and spong-network) are expected to sleep between +checking cycles. For spong-server this is the time to live for statuses. If +a status 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. +

$SPONGSLEEP{'DEFAULT'}, $SPONGSLEEP{'<program-name>'} +

+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 +$SPONGSLEEP{'DEFAULT'} value. If no value is then found, the spong program +will fall back to using $SPONGSLEEP. +

$SPONGSERVER +

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

+Multiple hosts can now be specified in <$SPONGSERVER>. This allows you to run +mutiple Spong Server instances for multiple monitored domains, and eventually +High Availability functionality. +

+The fully syntax is:
+
+   spong-server1.example.com[:port] [spong-server2.example.org[:port] ...]
+

+The '[:port]' specified the port the update process is listening on for that +Spong Server. See the $SPONG_UPDATE_PORT entry elsewhere in this document for more information. The default value +is 1998. +

$SPONG_UPDATE_PORT +

+This variable defines the port that the the spong-server manpage update process listens +on. If this variable is not defined on the $SPONGSERVER host, the +the spong-server manpage update process will not be started. The default value is 1998. +

$SPONG_QUERY_PORT +

+This variable defines the port that the the spong-server manpage query process listens +on. If this variable is not defined on the $SPONGSERVER host, the +the spong-server manpage query process will not be started. The default value is 1999. +

$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 $SPONGSERVER host, the +Big Brother BBSERVER emulation process will not be started. The default value +is 1984. +

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

$SPONG_LOG_FILE +

+If set to 1, spong-network will log errors to a log file in $SPONGTMP +named spong-network.log. +

$SPONG_LOG_SYSLOG +

+If set to 1, spong-network will log errors to the syslog using the +USER facility and the ERR priority. +

$TIMEFMT +

+A string that contains strftime() presentation symbols for formatting time +displays which have hours, minutes and seconds. The default is "%H:%M:%S". +

$TIMEFMTNOSEC +

+A string that contains strftime() presentation symbols for formatting time +displays which have hours and minutes. The default is "%H:%M". +

$DATEFMT +

+A string that contains strftime() presentation symbols for formatting date +displays. The default is "%m/%d/%y" (i.e numeric month / numeric day / + year w/o century ). +

$DATETIMEFMT +

+A string that contains strftime() presentation symbols for formating a full +date and time display. The default is "%c" (preferred date and time +representation for the current locale. And alternate format might be +"$DATEFMT, $TIMEFMT". +

spong-server

$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. +
$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. +
$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 +spong-server will terminated the connection. This action can be disables +by setting the variable to zero (0). +
$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. If the host has a 'display_name' attribute, it will be used +in preference to the FQDN names. +
$HISTORY_FQDN +: +Set this varirable to 1 to display teh fully qualified domain name (FQDN) of +hosts in History displays display clients. Otherwise only the first element of +the FQDN will be displayed. If the host has a 'display_name' attribute, it will +be used in preference to the FQDN names. +
+
$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; every time 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. +

www-spong

$WWW_USE_IMAGES +: +The variable controls how services status colors are displayed on the web +displays. If set to 1, service status colors are represented by colored icons. +Otherwise the colors are represented by blocks of color. +
+The default value is 0. If $WWW_USE_IMAGES is set, the the section on $WWWGIFS elsewhere in this document +variable must set to the location of the images directory. +
+
$WWWGIFS +: +When the section on $WWW_USE_IMAGES elsewhere in this document is set to 1, this variable should be +set to the URL path of the www/gifs directory within the document tree of +the web server. +
+The typical setup is to alias the /www directory of your installation to a +location in your document tree, for example alias /spong/ +/usr/local/spong/www/. Then set $WWWGIFS to /spong/gifs. +
+
$WWWDOCS +: +This is the URL path of the www/docs directory of within the document tree +of the web server. +
+The typical setup is to alias the /www directory of your installation to a +location in your document tree, for example alias /spong/ +/usr/local/spong/www/. Then set $WWWDOCS to /spong/docs. +
+
$WWWHTML +: +This should be the full path name to the www/html directory of your +Spong installation. +
$WWWSPONG +: +This should be the URL path to the location of the the www-spong manpage CGI program +with your web server's document tree. +
$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 variable $name holds the FQDN of the host being displayed. +
$WWW_PROB_ACTIONBAR +: +This variable is similar in function to the $WWW_ACTIONBAR_CUSTOM variable. +Except this action bar is display after each host listed in the problem +frame (left) of the client web interface. +
$WWW_TITLE_ACTIONBAR +: +This variable 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 the section on $WWWFRAMES elsewhere in this document is set to 3. +
$WWW_TITLE_COLOR +: +Defines the background color for table title cells in the client web interface. +The colors are defined in the HTML color format. +
$WWW_CELL_COLOR +: +This variable defined the background color for normal table cells in the +client web interface. The colors are defined in the HTML color format. +
$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. +
$WWWFRAMES +: +This determined the type of frame interface that is used in the web interface +client of the www-spong manpage. The variable can be set to 2 or 3. The default value is +2. See the user-guide manpage for more information. +
$WWW_TITLE_SIZE +: +This sets the vertical size of the title frame when the section on $WWWFRAMES elsewhere in this document is set +to 3. The values is a integer indication the number of points (as in font +sizes). The default value is 40. +
@WWW_REFRESH_ALLOW +: +A list of Perl regular expressions that are checked against the REMOTE_ADDR, +REMOTE_HOST and REMOTE_USER environmental CGI parables. If there is a match on +any of these variables the www-spong manpage will attach a REFRESH meta tag to reload +the web pages every the $SPONGSLEEP entry elsewhere in this document seconds. See the +the section on $WWW_REFRESH Logic in the admin-guide manpage for more details. +
@WWW_REFRESH_DENY +: +A list of Perl regular expressions that are checked against the REMOTE_ADDR, +REMOTE_HOST and REMOTE_USER environmental CGI parables. If there is a match on +any of these variables, the www-spong manpage will NOT attach a REFRESH meta tag. User's +must use the Reload/Refresh button on their web browser to update the Spong web +pages. See the the section on $WWW_REFRESH Logic in the admin-guide manpage for more +details. +
$WWWCONTACT +: +This is a partial URL to a CGI script that can do paging for systems. If it is +used a "Contact" link will appear on Tool Bar on Spong Web Displays. Refer to +the User Guide for more details. +
+There not sample CGI script provided. To create please see +the section on Custom Contacts in the admin-guide manpage. The variable is commented out and is not used +by default. +
+

www-spong-ack

$WWWSPONGACK +: +This should be the URL path to the location of the the www-spong-ack manpage CGI program +with your web server's document tree. +

spong-cleanup

$SPONG_ARCHIVE +: +The directory where to put old history file entries for each host. Each host +has 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. +

spong-client

@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 which 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 the check_logs manpage +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. +
+

spong-message

$MESSAGES_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

+These are various external programs that Spong uses to gather system +information to evaluate in it's checks. It is strongly> recommended that you +use the full path names for the values of these 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. +

FILES

SPONGHOME/etc/spong.conf +: +This is the standard spong.conf file that is read by all spong programs. +
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 host name of the machine you are running on (web1.school.edu), +or just the name minus the domain (web1). It looks for the full name +first, and then if it can not find it - it looks for the shorter name. +

AUTHOR

+Ed Hill <ed-hill@uiowa.edu>, Unix System Administrator, The University of +Iowa +

+Stephen L Johnson <sjohnson@monsters.org> +

HISTORY

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:06 2002 + + + diff --git a/www/docs/spong.groups.html b/www/docs/spong.groups.html new file mode 100644 index 0000000..6853f83 --- /dev/null +++ b/www/docs/spong.groups.html @@ -0,0 +1,191 @@ + + + + + + +spong.groups + + + + + +

spong.groups

NAME +
DESCRIPTION +
- %GROUPS +
+
FORMAT +
EXAMPLES +
SEE ALSO +
AUTHOR +
HISTORY +

NAME

+spong.groups - define groups of spong hosts +

DESCRIPTION

+The spong.hosts file defines two things. 1) The hosts you want to monitor +(and the attributes associated with each host), and 2) The humans that will +be contacted when a given host has problems (and the attributes associated +with each human). +

+The spong.groups file defines a set of hosts from spong.hosts. This +file is used by the Spong display programs www-spong and spong for +formating and filters output displays. The spong-message uses this +in it's messaging rules to do inclusion or exclusion of notifications for +groups of hosts. +

+Any number of groups can be added created. A host belong to multiple groups +or no groups. There is a default group of ALL which all hosts in spong.conf +are automatically a member. +

+Note: You do not have to add hosts into the 'ALL' group in the +spong.groups file. It is done automatically. +

%GROUPS

+Each host should have the following attributes associated with it: +

name
+
+The name of the group. This attribute is used extensively in Spong +Display programs. +
+
summary
+
+A description of the group +
+
members
+
+This is a list of host names that are members of the groups. The hosts names +should be those used in the spong.hosts program +
+

+Optionally, the follow attributes can also be assigned to a group: +

compress
+
+This attribute indicates whether or not empty empty service columns should +be removed when displaying this groups. Otherwise all of the services in +the Spong database will be shown. This attribute should be 0 or 1. The default +value is 0 (don't compress). +
+
display
+
+This attribute controls whether a group will be displayed on Host Groups +displays of Spong Display programs. Set this value off f you intend to just use +a group for notification matching spong-message. +
+
+This attribute should be 0 or 1. The default value is 1 (display the group). +
+

FORMAT

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

+What is expected in this file is the definition for one hash of hashes (in +Perl speak). The %GROUPS hash, If you are +not comfortable with Perl lingo, then just think of them as stanza definitions. +

+The following describes the <%GROUP> hash.
+
+  %GROUPS = ( [stanza], [stanza], [stanza] );
+

+where [stanza] is a second hash, that looks like the following:
+
+  'servers' => { name    => 'Main servers',
+                 summary => 'Main servers that are up 24x7',
+                 members => [ 'zero.monsters.org',
+                              'godzilla.monsters.org',
+                           ],
+                 compress = 0;
+                 display = 1;
+               }
+

+I know the format can be a little odd at first, but I chose it because +of both its simplicity to work with in the code (I don't have to parse +anything - Perl does all the work), and because it is easy to extend - +adding additional attributes is quite straightforward. +

EXAMPLES

+Here are some lines from my spong.groups file to show you possible +configurations. +

+  %GROUPS = (
+   'all' =>   { name    => 'All Systems',
+                summary => "This groups contains all hosts monitored by spong" },
+
+   'servers' => { name    => 'Main servers',
+                  summary => 'Main servers that are up 24x7',
+                  members => [ 'zero.monsters.org',
+                               'godzilla.monsters.org',
+                             ],
+                },
+
+   'windows' => { name => 'Windows Hosts',
+                  summary => 'Computers running Windows or NT',
+                  members => [ 'mothra.monsters.org',
+                            ],
+                  compress => 1,
+              },
+
+   'msgtest' => { name => 'spong-message groups',
+                  summary => 'A group to test spong-message rules matching',
+                  members => ['godzilla.monsters.org',
+                              'ghidora.monsters.org.',
+                             ],
+                  display => 0;  # Don't display this group
+
+  );
+

AUTHOR

+Ed Hill <ed-hill@uiowa.edu>, Unix System Administrator, The University of +Iowa +

+Stephen L Johnson <sjohnson@monsters.org> +

HISTORY

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:06 2002 + + + diff --git a/www/docs/spong.hosts.html b/www/docs/spong.hosts.html new file mode 100644 index 0000000..0be4835 --- /dev/null +++ b/www/docs/spong.hosts.html @@ -0,0 +1,306 @@ + + + + + + +spong.hosts + + + + + +

Next:
spong.message

Previous:
spong.groups

[Table of Contents]

[Index]

spong.hosts

NAME +
DESCRIPTION +
- %HOSTS +
- %HUMANS +
+
FORMAT +
EXAMPLE/h1 +
COMPARABILITY +In a future release of spong the %HUMAN configuration information will +be moved into the spong.message configuration file. It is currently being +retained in the spong.hosts file for compatibility. +
SEE ALSO +
AUTHOR +
HISTORY +

NAME

+spong.hosts - define hosts and services to monitor +

DESCRIPTION

%HOSTS

+Each host should have the following attributes associated with it: +

services
+
+the network services running on that host +
+

+Optionally, the follow attributes can also be assigned to a host: +

down | down:service
+
+time period(s) the host or a service on the host is scheduled down, problems +are not reported during this time. +
+
ip_addr
+
+a list of one or more ip addresses corresponding to multiple interfaces the +machine might have. +
+
skip_network_checks
+
+a flags (values 1 or 0) to tell the the spong-network manpage program to skip the +network checks for this host. +
+

+The services attribute is a string listing the network modules to run +against the host separated by spaces. The list of network modules included +with Spong is constantly growing, but they include ``dns'' , ``ftp'', ``smtp'', +``http'', ``imap'', ``pop3'', ``nntp'', ``nfs'',``ntp'' and ``ssh''. The list +can include any addition network checks that you have developed (see +the spong-network manpage and the developer-guide manpage for more details) . Any host listed is +automatically checked for network connectivity (via ping). The meta-service +``noping'' can be included in the list of modules to cause spong-network to +skip the ``ping'' test. +

+Service names in services can be flagged to skip the remaining checks if it
+fails. The tests that are slipped are flagged with a special "clear" status 
+color. The "clear" status mean they have not been checked due special
+circumstances. The service name is flagged by appending a colon (":") on the end
+of the service name. For example:
+
+  'myhost.org' => {  'services' => 'ping: ftp smtp' },
+

+Skip the 'ftp' and 'smtp' checks if the 'ping' check fails. +

+The down, down:servicename attributeis are a list of ``downtimes''. It is +a list (well reference to one anyway) of one or more strings in the following +format - ``d:hh:mm-hh:mm''. ``d'' is the day of the week (0-6, 0 = Sunday, 6 = +Saturday), if ``d'' is ``*'', then every day of the week is matched. The string +to the right of the day is the start and end time of the down time in 24 hour +format +

+The ip_addr attribute is a list (well reference to one anyway) of IP +address that the machine responds to. +

+The skip_network_checks flag be used to temporarily disable the network +checks for one or more hosts. The hosts can stll received spong-client status +updates. And the historical network information for the hosts is available. +This is useful when the hosts are being renamed or re-networked over an +extended period of time. +

+Additional attributes can be added into %HOSTS entries. These attributes +can be used for any external program or additional modules that you have +added to your Spong installation. All of the Spong programs will ignore any +attributes that they don't recognize. +

%HUMANS

+Each human that is defined should have the following attributes associated +with it: +

name
+
+name of the person to contact +
+

+And zero or more of the following attributes assigned to each human for +messaging when there are problems: +

email
+
+email address +
+
skytel
+
+skytel pager number +
+
alltelsms
+
+phone number of a phone subscriber to Alltel Communications SMS service. +
+
teletouch
+
+teletouch pager number +
+
teletouch_short
+
+teletouch pager number for small alpha pagers +
+
group
+
+A group of $HUMANS to contact. +
+

+These attributes are messaging modules names for sending out notifications to +people. All of the messing modules are loaded by spong-message as a plug-in +modules. The attributes listed above are the messaging modules that are part of +the current Spong distribution. New messaging modules can be easily be +developed. See the spong-message manpage and the the developer-guide manpage for more details). +

+The group attribute designates a group contact. It is a string that holds a
+list of one or more %HUMANS entries seperated by spaces or comma. The
+the spong-message manpage program will expand each entry in the group attribute
+to a seperate contact in the current the spong.message manpage file context. For
+example:
+
+ spong.hosts:
+   %HUMANS = ( 
+     'bob'   => { name => 'Bob Smith', email => 'bob@example.com', },
+     'ray'   => { name => 'Ray R.',    pager => '8145551234', }
+     'admins' => { name => 'Unix Admins', group => 'bob,ray' },
+   );
+
+ spong.message:
+   $MESSAGING_RULES = [
+     { hosts => ['dns.*'], services => ['dns'], 
+       contacts => [ { rcpts='admins', delay => 600, repeat=> 600 } ],
+     },
+   ];
+

+If the $MESSAGEING_RULES rule triggers, it will add 'bob' and 'ray' as contacts +with attributes of 'delay => 600' and 'repeat => 600'. +

FORMAT

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

+What is expected in this file are the definitions for two hashes of hashes (in +Perl speak). The %HOSTS hash, and the %HUMANS hash. If you are +not comfortable with Perl lingo, then just think of them as stanza definitions. +

+First, the HUMANS. The following describes the <%HUMANS> hash.
+
+   %HUMANS = ( [stanza], [stanza], [stanza] );
+

+where [stanza] is a second hash, that looks like the following:
+
+   'unix-staff' => { name => 'Midrange On-call Staff',
+                     email => 'unix-staff@school.edu',
+                     skytel => '1234567' },
+

+What this says is that the 'unix-staff' human has the following attributes +(name = Midrange On-call Staff, email = unix-statff@school.edu, skytel = +1234567). +

+Now, the HOSTS. The following describes the %HOSTS hash.
+
+   %HOSTS = ( [stanza], [stanza], [stanza] );
+

+where [stanza] is a second hash, that looks like the following:
+
+   'www.uiowa.edu' => { services => 'ftp smtp http',
+                        ip_addr  => ['192.168.15.2','10.2.124.200'],
+                        down      => [ '*:0015-0030','6:23:00-23:59']
+                     },
+

+What this says is that the 'www.uiowa.edu' host has the following attributes +(services = ftp smtp http; ip address=192.168.15.2 and 10.2.124.200; +and down time of 12:15AM-12:30AM every day and from 11:00PM-12:00PM on +Saturdays). +

+I know the format can be a little odd at first, but I chose it because +of both its simplicity to work with in the code (I don't have to parse +anything - Perl does all the work), and because it is easy to extend - +adding additional attributes is quite straightforward. +

EXAMPLE/h1

+Here are some lines from our spong.hosts file to show you possible
+configurations.
+
+   %HUMANS = (
+     'unix-staff' => { name  => 'Midrange On-call Staff',
+                       email => 'admin-staff@school.edu', },
+
+      'edhill'    =>  { name  => 'Ed Hill',
+                        email => 'ed-hill@school.edu',
+                        skytel => '1234567' },
+
+   );
+
+   %HOSTS = (
+
+     'strobe.weeg.school.edu' =>; { services => 'dns ftp smtp http',
+                                    ip_addr => [ '192.168.15.2',
+                                                 '10.2.124.200' ],
+                                    down => [ "*:05:30-06:30",
+                                              "0:00:00-04:00 ] },
+
+     'www.school.edu' => { services => 'ftp smtp http' },
+
+   );
+

COMPARABILITY +In a future release of spong the %HUMAN configuration information will +be moved into the spong.message configuration file. It is currently being +retained in the spong.hosts file for compatibility.

AUTHOR

+Ed Hill <ed-hill@uiowa.edu>, Unix System Administrator, The University of +Iowa +

+Stephen L Johnson <sjohnson@monsters.org> +

HISTORY

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:06 2002 + + + diff --git a/www/docs/spong.html b/www/docs/spong.html new file mode 100755 index 0000000..2607cff --- /dev/null +++ b/www/docs/spong.html @@ -0,0 +1,175 @@ + + + + + + +spong + + + + + +

Next:
spong-ack

Previous:
pre_redirect

[Table of Contents]

[Index]

spong

NAME +
SYNOPSIS +
DESCRIPTION +
OPTIONS +
CONFIGURATION +
- Configuration Files +
- Configuration Variables +
+
FILES +
DEPENDENCIES +
BUGS +
SEE ALSO +
AUTHOR +
HISTORY +

NAME

+spong - character based Spong client interface program +

SYNOPSIS

DESCRIPTION

+The spong program interfaces with the spong-server to display the +collected information; in text format. The spong program does not have all +of the functionality of the web-based interface. It's designed to be used from +character based consoles. The spong program doesn't not have to load onto the +same machine that spong-server is running on. You load this program onto any +machine. It is a good ideal to load this onto machines, when possible, to allow +the administrator of the machine to query the spong-server when alert of +received. +

+When run with any parameters, spong will display a table that lists +the hosts and services. All of the displays are text based with the legends +at the top. +

OPTIONS

--summary [HOSTLIST] +: +Summarize the status of hosts, in HOSTLIST, in a table that lists +the hosts and services, and the current status is a single letter with +the meaning defined in the legend at the top of the display. If HOSTLIST +if not specified all hosts defined in spong.hosts are displayed. +
--problems [HOSTLIST] +: +Shows a summary of all the problems (services that are red) for the all +the hosts in <HOSTLIST>. If HOSTLIST is not specified, all hosts defined +in spong.hosts are displayed. +
--history [HOSTLIST] +: +Show history information for the the list of hosts in HOSTLIST. If +HOSTLIST is not specified, all hosts defined in spong.hosts are +displayed. +
--host HOST +: +Shows all information available for the given HOST +
--services host +: +Shows detailed service information for the given HOST. +
--stats HOST +: +Show statistical information for the given HOST. (Not currently +implemented.) +
--config HOST +: +Shows configuration information for the given HOST. (Not currently +implemented.) +
--info HOST +: +Shows admin supplied text for the given HOST. +
--service HOST:SERVICE +: +Shows detailed information for the given HOST/SERVICE. +
--brief +: +Display output in a brief format. +
--standard +: +Display output in standard format (the default) +
--full +: +Display the maximum amount of information possible. +

CONFIGURATION

Configuration Files

+By default the the spong.conf manpage file is read on startup. It defines some specific +variable that you probably don't need to override. +

+After reading the configuration file, then reads the +spong.conf.[host] file where [host] is the host name 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. +

Configuration Variables

+Here are a list of variables in the spong.conf file that are applicable +to the spong-server program: +

$SPONGSERVER +: +The make of the server that spong-server is running on. +
$SPONG_QUERY_PORT +: +The port number that spong-server listens at for database queries. +

FILES

spong.conf +: +Configuration file. This contains variables that detail spong and OS specific +definitions used by spong-server. +

DEPENDENCIES

+Perl v5.005_03 or greater is required. +

BUGS

+The --stats, --config, and --info parameters are currently +not implemented in the spong-server. When specified they will just generate +a blank HTML page. +

AUTHOR

+Ed Hill <ed-hill@uiowa.edu>, Unix System Administrator, The University of +Iowa +

+Stephen L Johnson <sjohnson@monsters.org> +

HISTORY

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:01 2002 + + + diff --git a/www/docs/spong.message.html b/www/docs/spong.message.html new file mode 100644 index 0000000..23e4edc --- /dev/null +++ b/www/docs/spong.message.html @@ -0,0 +1,443 @@ + + + + + + +spong.message + + + + + +

Next:
spongfaq

Previous:
spong.hosts

[Table of Contents]

[Index]

spong.message

NAME +
DESCRIPTION +
CONFIGURATION VARIABLES +
- $RULES_MATCH +
- $MESSAGING_RULES +
+
FORMAT +
MESSAGE TEMPLATES +
- Messaging Modules +
+
MATCHING LOGIC +
EXAMPLES +
COMPATIBILITY +
SEE ALSO +
AUTHOR +
HISTORY +

NAME

+spong.message - define rules on how and when to send notifications +

DESCRIPTION

+The spong.message file defines the rules that spong-message program used +for notifications. The rules consist of attributes which define criteria +which events are matched against and a list of contacts to notify if all +of the matching criteria are met. +

CONFIGURATION VARIABLES

$RULES_MATCH

+The variable governs the matching rules are processed. The possible values +are 'OLD', 'FIRST-MATCH', or 'ALL'. +

OLD +: +This cause spong-message to use the notification logical from Spong 2.1. +This is intended an aid in migrating a Spong 2.1 installation to Spong 2.5 +and above. The existing notification scheme can be used until new messaging +rules are developed and debugged. +
+This functionality will be removed at some point in the future. +
+
FIRST-MATCH +: +This value causes the rules matching engine to stop after the first successful +match. The matching rule is processed, and then the spong-message program +terminates. +
ALL +: +This values causes the rules matching engine to scan all rules. It will +process all successful matches. +

$MESSAGING_RULES

+Each rule should have more of more of the following matching +terms: +

name
+
+The is a comment field to allow the rule to be described. This field +is printed on certain lines when the --debug switch is specified. +
+
hosts
+
+A list of one or more regular expressions that are matched against the host +name of the status event. If the one of the expression matches the host name, +the term is considered matched. +
+
host_groups
+
+A list of one or more host group names from spong.groups (see +the spong.groups manpage). The host name of the event check against all of the members +of the specified groups. If it is found, this attribute is considered matched. +
+
services
+
+A list of one or more regular expressions that are matched against the service +name of the status event. If one of the expression matches the service name, +the term is considered matched. +
+
times
+
+A list of one or more day-of-week ranges and/or time ranges combinations which +are checked against the time stamp of the status event. If one of the day/time +combinations matched, the term is considered matched. +
+
exclude_hosts
+
+A list of one or more regular expressions that are matched against the host +name of the status event. If at least one of the expressions matches the host +name, the term is considered an exclusion match. +
+
exclude_services
+
+A list of one or more regular expressions that are matched against the host +name of the status event. If at least one of the expressions matched the service +name, the term is considered an exclusion match. +
+
exclude_host_groups
+
+A list of one or more host group names from the spong.groups (see the spong.groups manpage). If the host name of the status event is a member of one of the host +groups, the term is considered an exclusion match. +
+
exclude_colors or exclude_status
+
+A list of one of more status colors ('red', 'yellow', or 'green'). If the +status color is the event matches one of the colors in the list, the term is +considered an exclusion match. +
+
last_if_match
+
+A flag that can have the value of '1' or '0'. The rules scanner will quit +processing if last_if_match is set for a rule and all of the matching +terms succeed. This flag is only usefull if the the $RULES_MATCH entry elsewhere in this document configuration +variable is set to ALL. +
+

+And each rule must have the following attributes: +

contacts
+
+A list of contact stanzas that are to be notified if the rules is matched. +
+

+Each of the elements of the hosts, services, exclude_hosts, and +exclude_services are actually Perl regular expressions. You can use wide +cards to specify which groups of hosts or services to match. +

+The times term is a list of stanzas that have days of the week +(days) and/or time ranges (times) to match against the time parameter +passed to spong-message. Each times stanza can have a days and/or a times +attributes. +

+The days attributes are a list of strings with the following format - +'d' or 'd-d'. Where d is the day of the where (0-6, 0=Sunday, 6=Saturday). +And 'd-d' represents a range of days (i.e. 1-5 = Monday - Friday). +

+The times attributes are a list of string with the following format - +'hh:mm-hh:mm'. This is a starting and ending time of a time range in 24 +hour format. +

+Note: The down attribute in a host's entry in the spong.hosts file has the effect of an "exclude_times" term for the host. If the timestamp of +a status event matched on a down downtime period, no notifications will +be sent. See the section on down in the spong.hosts manpage for more details. +

+The contacts term is a list of stanzas representing the contacts to notify +if the rule's matching criteria are met. Each stanza can be +a string or a contact stanza. The strings can be one of the following +formats - 'human', 'human:func' where human is a strings represent an +entry from the %HUMANS defined in spong.hosts +and func is one of the message module attributes defined for that human. +

+A contact entry can also be a stanza The stanza must have a 'rcpt' attribute +which is a contact strings as defined above (i.e. 'human' or 'human:func'). +It can also have an optional delay and/or repeat attribute. The delay +attribute is the duration, in seconds, that an event be in an alert status +before the rcpt is notified. The repeat attribute is the time interval, +in seconds, in which notifications are resent once an initial notification is +sent. +

FORMAT

+The spong.message file is simply Perl code that gets imported the +spong-message program, so the only real format restrictions is just what is +syntactically correct in Perl (which some would say is anything 8-). +

+What is expected in this file are the definition for the $MESSAGING_RULES
+and $RULES_MATCH which determines how the rules are processed.  If you are
+not comfortable with Perl lingo, then just think of them as stanza definitions.
+
+    $MESSAGING_RULES = [ [stanza], [stanza], [stanza] ]
+

+where [stanza] is a second hash, that looks like the following:
+
+  { hosts => [ 'unixweb', '.*-ops.cic.myschool.edu', 'steves-pc' ]
+    services => [ '.*' ],
+    exclude_hosts => [ 'backup-ops.cic.myschool.edu'],
+    exclude_services => [ 'dns', 'ssh'],
+    times => [
+               { days=> ['0','1-3','4-5'],
+                 times=> ['06:30-18:30','21:00-22:00'
+               },
+               { days => ['5','6','0-2'] },
+               { times => ['13:00-15:23','00:00-23:39'] },
+             ],
+    contacts => [ 'ops', 'sjohnson:email',
+                  { rcpt=>'sjohnson:teletouch', delay=>900, repeat=>600 },
+                  { rcpt=>'the_supervisor:teletouch', delay=3600,
+                    repeat=>1800 },
+                  # This contact should get be notified or else !!!!!
+                  { rcpt=>'the_boss', delay=>7200, repeat=>3600 },
+                ],
+  },
+

+The $RULES_MATCH variable has three possible values: +

OLD +: +Use Spong ver 2.1 messaging. Send notification the human defined in the +contact attribute for the host name of the message. +
FIRST-MATCH +: +Rules are checked in order until the first rules matches. Contacts are notified and spong-message exits. +
ALL +: +Rules are checked into order. All matching rules are processed. +

+I know the format can be a little odd at first and overwhelming at first, but I +chose it because of both its simplicity to work with in the code (I don't have +to parse anything - Perl does all the work), and because it is easy to extend - +adding additional attributes is quite straightforward. +

MESSAGE TEMPLATES

+Notification messages formats are determined by the templates in the +%TEMPLATES variable in the spong.message file. Templates are searched +according to the following order: 'contact:module', 'module', 'contact', +'DEFAULT'. +

+Any text in a template string is added verbatim to the message. The list of +substitution variables can be added to the template strings. +

!!HOST!! +: +Full domain of the system of the event message. +
!!SHORTHOST!! +: +The short host name of the system of the event message. +
!!COLOR!! and !!STATUS!! +: +The status color ('green', 'yellow', or 'red') of the status message. +
!!WWWSPONG!! +: +The $WWWSPONG URL variable from the spong.conf configuration variable. +
!!SUMMARY!! +: +The summary message field in the status message. +
!!DETAILED!! +: +The detailed message field of the status message. The value of this variable +can be very large and have multiple lines of text. +
!!DETAILEDHTML!! +: +This is the same the !!DETAILED!! except that the field is HTMLized (i.e. +newlines replaced with , etc.). This will allow HTML message to be sent +and formatted properly. +
!!CURTIME!! +: +The current system time formatted according to $DATETIMEFMT +
!!DATE!! +: +The date of the event message formatted according to $DATEFMT +
!!TIME!! +: +The date of the event message formated according to $TIMEFMT +
!!DATETIME!! +: +The date/time of the event message formatted according to $DATETIMEFMT +

Messaging Modules

MATCHING LOGIC

+The primary factor of how spong.message rules are processed depends upon the +value of $RULES_MATCH. If set to 'OLD' then the rules are not used at all. +spong-message reverts back to it Spong version 2.1 behavior. Notify the +human defined in the contact attribute of the %HOST/b entry for the host. +

+This functionality included for backwards compatibility and to aid in migrating old Spong vers 2.0 and Spong 2.1 installations to the current version. It will +be removed some future version of Spong. +

+If %RULES_MATCH is set to 'FIRST-MATCH' then the rules are check in order +until the first rule matching the event parameters. spong-message will then +begin notification processing. All of the contacts will be notified and then +the program will exit. +

+If $RULES_MATCH is set to 'ALL' then all +of the rules are scan in order. The contacts of all matching rules are adding +to the list of recipients that will be notified. After rule matching is +finished all of the contacts are be notified. +

+All of the matching attributes except for exclude_hosts, +exclude_services and exclude_host_groups have an automatic "match if +absent" property. For example, if the hosts attribute is missing from a +rule, that rule will match any host name. +

+The exclude_hosts, exclude_services, and exclude_host_groups terms +have a slightly different matching behavior man the others. If there is a +match against any of them, the rule will not match even if all of the other +terms match. For example, if a rules has hosts = [ '.*.cic.my-company', +'.*.corp.my-company.com' ]> and exclude_hosts[ 'my-pc' ], a host name of +'my-pc.corp.my-company.com' will not match against this rule because of the +host name matches the exclude_hosts attribute. +

+The times term's attributes, days and times , have the automatic +"match if absent" property also. If one of the sub-attributes is missing from a +stanza any check against that attribute will succeed. That is, if days is +missing from the stanza, any day of the week will match against the stanza. If +the times attribute is missing, the stanza matches against any +time. +

EXAMPLES

+Here are some lines from our spong.hosts file to show you possible
+configurations.
+
+  $MESSAGING_RULES = [
+
+      # Franks Notifications
+      # Let him know about if it has been down for 30 minute or more.
+      {
+         hosts => [ '.*' ],
+         services => [ '.*' ],
+         contacts => [ {rcpt=>'fsipes', delay=>1800}, ],
+         exclude_hosts => ['tunixt'],
+         exclude_services => ['test'],
+      },
+
+      # Please note the previous stanza can also be written as follows
+      # Both stanzas are equivalent.
+      {
+         contacts => [ {rcpt=>'fsipes', delay=>1800}, ],
+         exclude_hosts => ['tunixt'],
+         exclude_services => ['test'],
+      },
+
+      # Let Dwayne in Engineering know when a system does down and dns problems
+      # except for the test box and only send him down messages
+      {
+          hosts => ['.*'],
+          services => ['ping','ftp','smtp','dns'],
+          exclude_host => ['tunixt'],
+          exclude_colors => ['green','yellow']
+          contacts => [ 'dstucker' ],
+      },
+
+      # Let me know about everything except the test box except late at
+      # night
+      {
+         hosts => ['.*'],
+         services => ['.*'],
+         exclude_services => ['nntp','ntp'],
+         exclude_hosts => ['tunixt'],
+          contacts => ['sjohnson'],
+          times => [
+                    { times => ['06:00-21:00'] },
+                   ],
+      },
+
+      # Notify the unix oncall pager about the k12 systems after hours
+      # during week days and anytime on the weekend and repeat them
+      # every 15 minutes until acknowledged
+      {
+          host_groups => [ 'apscn' ],
+          exclude_services => ['nntp','ntp'],
+          exclude_hosts => ['tunixt'],
+          contacts => [ { rcpt=>'unix-oncall:teletouch', repeat=>900}, ],
+          times => [
+                { days => ['1-5'], times => ['17:00-23:59','00:00-08:00'] },
+                { days => ['0','6'] },
+                   ],
+          },
+
+    ];
+

COMPATIBILITY

+To use Spong version 2.1 spong-message and messaging configurations set +$RULES_MATCH to 'OLD'. If $RULES_MATCH is not defined it will default +to 'OLD'. +

AUTHOR

+Ed Hill <ed-hill@uiowa.edu>, Unix System Administrator, The University of +Iowa +

+Stephen L Johnson <sjohnson@monsters.org> +

HISTORY

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:07 2002 + + + diff --git a/www/docs/spongfaq.html b/www/docs/spongfaq.html new file mode 100644 index 0000000..f8c4718 --- /dev/null +++ b/www/docs/spongfaq.html @@ -0,0 +1,237 @@ + + + + + + +spongfaq + + + + + +

Next:
todo

Previous:
spong.message

[Table of Contents]

[Index]

spongfaq

NAME +
DESCRIPTION +
+
AUTHORSHIP and COPYRIGHT +

NAME

+spongfaq - frequently asked questions about Spong ($Revision: 1.1 $, $Date: 2005/09/30 07:47:25 $) +

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

1. What is Spong?

+This is hopefully a 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: +

client based monitoring (CPU, disk, processes, logs, etc...)
+
monitoring of network services (smtp, http, ping, pop, dns, etc...)
+
grouping of hosts (routers, servers, workstations, PCs)
+
rules based messaging when problems occur
+
configurable on a host by host basis
+
results displayed via text or web based interface
+
history of problems
+
verbose information to help diagnosis problems
+

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 machine. 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 gethost-test in the /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 perl gethost-test. +

+If none of the above works or can't make the changes, you still have one last +resort. The spong.conf and spong.conf.<hostname> file are loaded +after the $HOST variable is assigned. That mean that you can override the +calculated $HOST hostname. Just added at '$HOST = "desired host name";' +statement in either of the spong.conf or spong.conf.<hostname> +files. +

3. How do I get e-mail/paging/alpha paging/notifications to work?

+The most important thing is to go through the the spong.conf manpage, the spong.hosts manpage, +and the spong.message manpage configuration files. And be sure to read the documentation +for the spong.conf manpage, the spong.hosts manpage the spong.message manpage, configuration files and the +the spong-message manpage and the spong-server manpage programs. +

+If you are still having problems, follow the check list below to help +resolve your problem. +

$SEND_MESSAGE in spong.conf
+
+In spong.conf make sure the $SEND_MESSAGE is set to 'RED', 'CHANGE' or +'RED-CHANGE'. +
+
$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. +
+

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

%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',
+                    },
+   );
+

Testing messaging rules
+
+If you have a problem with your messaging rules, The spong-message program has +a debugging and test mode. These modes will allow you to check, test and tweak +your messaging rules in spong.message. +
+
```
+Run the spong-message program from a command line as follows:
+
+  spong-message --debug --test color host service `perl -e "print time()"` \
+     'This is a test.'
+
```
+
+The --debug flag will output a large amount of detailed output about what the +program is doing. The --test flag if the test mode flag. Spong-message will do +everyting but send out the notifications. +
+
+color = status color - green, yellow, or red +hostname = a hostname from your spong.hosts file +service = a service name that you are testing. +
+
+The back-ticked perl expression just prints the current system time in epoch +format. And the "The is a test." field is the summary message from a status +update message. +
+
+The --debug output is very detailed about every step that the spong-message +program is doing. You may need to redirect the output to a file in order to +look at. +
+
+Spong Message will detail step-by-step all of the matched it attempts and the +resultsand actions of those matches. It will refer to rules by an index number +starting with the number zero (0) for the first rule. +
+
```
+To test days and times ranges your will need to caculate a specific date/time 
+into an epoc or calender time format to feed it to spong-message. You can use 
+this short perl code snippet to do it.
+
+  perl -MPOSIX -e 'print mktime(  sec, min, hour, day, (month - 1) , \
+               (year - 1900) ), "\n"'
+
```
+
+The time is in 24 hour format and the year is the 4 digit year. This will +print a large number. Use the number in place of the back-ticked perl +expression on spong-message command. +
+
Testing with spong-server
+
+The best way to test everything to set $SEND_MESSAGE to 'CHANGE' and run +spong-server in debug mode with a debug level of at least 3 (i.e. spong-server +--debug 3 ). This will cause spong-server to call spong-message for every +chagne in status of any host . And spong-server will call spong-message in +debug mode also. This will let you see everying that spong-server and +spong-message is doing. You will see spong-server say something like "change in +state to red messaging a human." in it's debug output when it is sending out +notifications. +
+
+Once you have your single contact / single messaging rule configuration +working. Change $SEND_MESSAGE to what you desire. And then start adding in +more messaging rules and contacts. But continue testing your spong.message +config file as described above (see "Testing Messaging Rules"). +
+

AUTHORSHIP and COPYRIGHT

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:07 2002 + + + diff --git a/www/docs/spongindex.html b/www/docs/spongindex.html new file mode 100644 index 0000000..ebba94d --- /dev/null +++ b/www/docs/spongindex.html @@ -0,0 +1,308 @@ + + + + + + +Index + + + + + +

Previous:
www-spong-ack

[Table of Contents]

[Index]

Index

A

+a more detailed message providing additional detail.  [spong-client]  [spong-network]
+a one line summary  [spong-client]  [spong-network]
+ack-id  [spong-ack]
+Acknowledge Problem Display  [user-guide]
+Acknowledgements  [user-guide]
+Action Bar  [user-guide]  [user-guide]  [user-guide]  [user-guide]
+ALL  [spong.message]  [spong.message]
+alltelsms  [spong.hosts]
+

B

+--batch  [spong-ack]
+--brief  [spong]  [www-spong]
+BLUE  [user-guide]
+

C

+!!COLOR!! and !!STATUS!! [spong.message]
+!!CURTIME!! [spong.message]
+$CHECKS [spong-client]
+$color [developer-guide]
+$CPUWARN, $CPUCRIT [spong-client] [spong.conf]
+--cmd status|page [spong-status]
+--color <COLOR> [spong-status]
+--color|--status color [spong-message]
+--config HOST [spong]
+--config host [www-spong]
+cgi-bin/ [admin-guide]
+CHECK [developer-guide]
+checks [spong-client]
+CLEAR [user-guide]
+client based monitoring (CPU, disk, processes, logs, etc...) [spongfaq]
+cmd [spong-server-mod-template] [spong-server-mod-template] [spong-server-mod-template]
+color [developer-guide] [developer-guide] [spong-message] [spong-server-mod-template]
+COLOR [developer-guide]
+color ("red", "yellow", "green") [spong-client] [spong-network]
+command [developer-guide] [developer-guide]
+compress [spong.groups]
+configurable on a host by host basis [spongfaq]
+contacts [spong.message]
+

D

+!!DATE!!  [spong.message]
+!!DATETIME!!  [spong.message]
+!!DETAILED!!  [spong.message]
+!!DETAILEDHTML!!  [spong.message]
+$DATEFMT  [spong.conf]
+$DATETIMEFMT  [spong.conf]
+$DF, $UPTIME, $PS, $GREP  [spong-client]
+$DF, $UPTIME, $PS, $GREP, $PING, $TRACEROUTE, $MAILQ  [spong.conf]
+$duration  [developer-guide]
+%DFWARN, %DFCRIT  [spong.conf]
+--debug  [spong-ack]  [spong-message]
+--delete  [spong-ack]
+@DFIGNORE  [spong.conf]
+DATA  [developer-guide]
+Detail Message Field  [check_interfaces]  [check_snmp]
+Detailed Information  [user-guide]
+detailed status message  [developer-guide]  [developer-guide]
+display  [spong.groups]
+down | down:service  [spong.hosts]
+drop_msg  [spong-server-mod-template]
+duration  [spong-client]  [spong-server-mod-template]
+

E

+email  [spong.hosts]
+end_time  [spong-server-mod-template]  [spong-server-mod-template]
+exclude_colors or exclude_status  [spong.message]
+exclude_host_groups  [spong.message]
+exclude_hosts  [spong.message]
+exclude_services  [spong.message]
+Expected System Object ID  [check_snmp]
+

F

+--file FILENAME  [spong-status]
+--file filename  [spong-message]
+--full  [spong]  [www-spong]
+FIRST-MATCH  [spong.message]  [spong.message]
+FLAGS  [developer-guide]
+

G

+%GROUPS  [spong-server]
+--grp-problems  [www-spong]
+--grp-summary  [www-spong]
+GREEN  [user-guide]
+group  [spong.hosts]
+Group Section  [user-guide]
+Group Summary Display  [user-guide]
+grouping of hosts (routers, servers, workstations, PCs)  [spongfaq]
+

H

+!!HOST!!  [spong.message]
+$HISTORY_FQDN  [spong-server]  [spong.conf]
+$host  [developer-guide]
+%HOSTS  [spong-message]  [spong-network]  [spong-server]
+%HTTPDOCS, %HTTPPORT  [spong.conf]
+%HUMANS  [spong-message]
+%HUMANS in spong.hosts  [spongfaq]
+--help  [spong-status]
+--history [hostlist]  [www-spong]
+--history [HOSTLIST]  [spong]
+--host host  [www-spong]
+--host HOST  [spong]
+--host hostname  [spong-message]
+--host NAME  [spong-status]
+header  [spong-server-mod-template]  [spong-server-mod-template]  [spong-server-mod-template]
+History  [user-guide]
+history of problems  [spongfaq]
+host  [developer-guide]  [developer-guide]  [spong-ack]  [spong-message]  [spong-server-mod-template]  [spong-server-mod-template]  [spong-server-mod-template]
+HOST  [developer-guide]  [developer-guide]  [developer-guide]
+Host Services Display  [user-guide]
+host_groups  [spong.message]
+hostname (where is this report coming from)  [spong-client]  [spong-network]
+hosts  [spong.message]
+

I

+$IDENT_MESSAGES_PER_HOUR  [spong-message]  [spong.conf]
+--info HOST  [spong]
+--info host  [www-spong]
+id  [spong-client]
+Ignored Interfaces  [check_interfaces]
+Information  [user-guide]
+ip_addr  [spong.hosts]
+

L

+$LOGCHECKS  [spong-client]  [spong.conf]
+Last Update  [user-guide]
+last_if_match  [spong.message]
+logfile  [spong-client]
+

M

+$message  [developer-guide]
+$MESSAGES_PER_HOUR  [spong-message]  [spong.conf]
+$MESSAGING_RULES  [spong-message]
+--message "message text"  [spong-message]
+--message TEXT  [spong-status]
+Main Section  [user-guide]
+members  [spong.groups]
+Memory leak in spong-network on RedHat 6.0  [spong-intro]
+MESSAGE  [developer-guide]  [developer-guide]
+message  [spong-ack]  [spong-message]  [spong-server-mod-template]  [spong-server-mod-template]
+Messaging rules in spong.message  [spongfaq]
+monitoring of network services (smtp, http, ping, pop, dns, etc...)  [spongfaq]
+

N

+name [spong.groups] [spong.hosts] [spong.message]
+

O

+$OLD_HISTORY  [spong-cleanup]  [spong.conf]
+$OLD_SERVICE  [spong-cleanup]  [spong.conf]
+OLD  [spong.message]  [spong.message]
+Overall Status  [user-guide]
+

P

+--problems [hostlist]  [www-spong]
+--problems [HOSTLIST]  [spong]
+@PROCSWARN, @PROCSCRIT  [spong-client]  [spong.conf]
+pattern  [spong-client]
+PORT  [developer-guide]  [developer-guide]
+PURPLE  [user-guide]
+

R

+$RULES_MATCH  [spong-message]
+$RULES_MATCH in spong.conf  [spongfaq]
+RECIPIENT  [developer-guide]
+RED  [user-guide]
+results displayed via text or web based interface  [spongfaq]
+rules based messaging when problems occur  [spongfaq]
+

S

+!!SHORTHOST!! [spong.message]
+!!SUMMARY!! [spong.message]
+$SEND_MESSAGE [spong-message] [spong.conf]
+$SEND_MESSAGE in spong.conf [spongfaq]
+$SENDMSG_SERVERS [data_sendmsg]
+$SPONG_ARCHIVE [spong-cleanup] [spong.conf]
+$SPONG_BB_UPDATE_PORT [spong-server] [spong.conf]
+$SPONG_LOG_FILE [spong-client] [spong-network] [spong-server] [spong.conf]
+$SPONG_LOG_SYSLOG [spong-client] [spong-network] [spong-server] [spong.conf]
+$SPONG_QUERY_PORT [spong] [spong.conf] [www-spong]
+$SPONG_SERVER_ALARM [spong-server] [spong.conf]
+$SPONG_UPDATE_PORT [spong-ack] [spong-server] [spong-server] [spong-status] [spong.conf] [www-spong-ack]
+$SPONGDB [spong-cleanup] [spong-server] [spong.conf]
+$SPONGDB/<hostname>/info/info.brief.html [admin-guide]
+$SPONGDB/<hostname>/info/info.brief.txt [admin-guide]
+$SPONGDB/<hostname>/info/info.full.html [admin-guide]
+$SPONGDB/<hostname>/info/info.full.txt [admin-guide]
+$SPONGDB/<hostname>/info/info.html [admin-guide]
+$SPONGDB/<hostname>/info/info.standard.html [admin-guide]
+$SPONGDB/<hostname>/info/info.standard.txt [admin-guide]
+$SPONGDB/<hostname>/info/info.txt [admin-guide]
+$SPONGSERVER [spong] [spong-ack] [spong-status] [spong.conf] [www-spong] [www-spong-ack]
+$SPONGSLEEP (Depreciated) [spong-server] [spong.conf]
+$SPONGSLEEP, $SPONGSERVER, $SPONG_UPDATE_PORT [spong-client] [spong-network]
+$SPONGSLEEP{'DEFAULT'}, $SPONGSLEEP{'<program-name>'} [spong.conf]
+$SPONGSLEEP{'DEFAULT'}, $SPONGSLEEP{'spong-client'} [spong-client]
+$SPONGSLEEP{'DEFAULT'}, $SPONGSLEEP{'spong-network'} [spong-network]
+$SPONGSLEEP{'DEFAULT'}, $SPONGSLEEP{'spong-server'} [spong-server]
+$SPONGSLEEP{'www-spong'} or $SPONGSLEEP{'default'} [www-spong]
+$SPONGSTATUS [spong-server] [spong.conf]
+$SPONGTMP [spong-client] [spong-network] [spong-server] [spong.conf]
+--service HOST:SERVICE [spong]
+--service host:service [www-spong]
+--service NAME [spong-status]
+--service service [spong-message]
+--services host [spong] [www-spong]
+--standard [spong] [www-spong]
+--stats host [www-spong]
+--stats HOST [spong]
+--summary "summary text" [spong-message]
+--summary [hostlist] [www-spong]
+--summary [HOSTLIST] [spong]
+--summary TEXT [spong-status]
+@SENDMSG_EXCL_HOSTS [data_sendmsg]
+@SENDMSG_INC_HOSTS [data_sendmsg]
+SEND [developer-guide]
+SERVERADDR [developer-guide]
+service [developer-guide] [developer-guide] [spong-ack] [spong-message] [spong-server-mod-template] [spong-server-mod-template] [spong-server-mod-template]
+SERVICE [developer-guide] [developer-guide]
+service name ("disk", "cpu", "procs", "logs", "local") [spong-client] [spong-network]
+Service Status Display [user-guide]
+services [spong.hosts] [spong.message]
+Services Table [user-guide]
+skip_network_checks [spong.hosts]
+skytel [spong.hosts]
+SNMP Community Name [check_interfaces] [check_snmp]
+Spong CGI Directory [admin-guide]
+Spong HTML Directory [admin-guide]
+spong-bb-update [admin-guide]
+spong-query [admin-guide]
+spong-update [admin-guide]
+spong.conf [admin-guide] [spong] [spong-network] [spong-server] [www-spong]
+spong.conf.[hostname] [spong-network] [spong-server]
+spong.groups [spong-server]
+spong.hosts [spong-message] [spong-message] [spong-network] [spong-server]
+spong.message [spong-message] [spong-message]
+SPONGHOME/etc/spong.conf [spong.conf]
+SPONGHOME/etc/spong.conf.[host] [spong.conf]
+start_time [spong-server-mod-template]
+status [spong-client]
+STATUS [developer-guide]
+Status [check_interfaces] [check_snmp]
+stop_after [admin-guide]
+summary [developer-guide] [developer-guide] [spong-server-mod-template] [spong.groups]
+SUMMARY [developer-guide] [developer-guide]
+Summary Field [check_interfaces] [check_snmp]
+Summary Information [user-guide]
+

T

+!!TIME!!  [spong.message]
+$time  [developer-guide]
+$TIMEFMT  [spong.conf]
+$TIMEFMTNOSEC  [spong.conf]
+$TIMEFMTNOSEC and $DATEFMT  [www-spong]
+%TEMPLATES  [spong-message]
+--time time  [spong-message]
+--ttl SECONDS  [spong-status]
+teletouch  [spong.hosts]
+teletouch_short  [spong.hosts]
+Testing messaging rules  [spongfaq]
+Testing with spong-server  [spongfaq]
+text  [spong-client]
+time  [admin-guide]  [developer-guide]  [developer-guide]  [spong-ack]  [spong-message]  [spong-server-mod-template]
+times  [spong.message]
+Title  [user-guide]  [user-guide]  [user-guide]
+TTL  [developer-guide]
+

U

+user [spong-server-mod-template]
+

V

+verbose information to help diagnosis problems  [spongfaq]
+Version 1.0  [spong-intro]
+Version 1.1  [spong-intro]
+Version 2.0  [spong-intro]
+Version 2.5  [spong-intro]
+Version 2.6  [spong-intro]
+Version 2.7  [spong-intro]
+View Tool Bar  [user-guide]
+

W

+!!WWWSPONG!!  [spong.message]
+$WWDOCS  [admin-guide]
+$WWW_ACTIONBAR_CUSTOM  [spong.conf]
+$WWW_CELL_COLOR  [spong.conf]
+$WWW_COLOR{...}  [spong.conf]
+$WWW_FQDN  [spong-server]  [spong.conf]
+$WWW_PROB_ACTIONBAR  [spong.conf]
+$WWW_TITLE_ACTIONBAR  [spong.conf]
+$WWW_TITLE_COLOR  [spong.conf]
+$WWW_TITLE_SIZE  [spong.conf]
+$WWW_USE_IMAGES  [spong.conf]
+$WWWACK  [admin-guide]
+$WWWCONTACT  [spong.conf]
+$WWWDOCS  [spong.conf]
+$WWWFRAMES  [spong.conf]  [www-spong]
+$WWWGIF  [admin-guide]
+$WWWGIFS  [spong.conf]
+$WWWHTML  [admin-guide]  [spong.conf]
+$WWWSPONG  [admin-guide]  [spong.conf]
+$WWWSPONGACK  [spong.conf]
+@WWW_REFRESH_ALLOW  [spong.conf]
+@WWW_REFRESH_DENY  [spong.conf]
+Web Server Configuration  [admin-guide]
+www/  [admin-guide]
+

Y

+YELLOW [user-guide]
+

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:09 2002 + + + diff --git a/www/docs/spongtoc.html b/www/docs/spongtoc.html new file mode 100644 index 0000000..6449f0b --- /dev/null +++ b/www/docs/spongtoc.html @@ -0,0 +1,53 @@ + + + + + + +Table of Contents + + + + + +

Next:
admin-guide

[Table of Contents]

[Index]

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

admin-guide	admin-guide - Spong Administrator's Guide
check_interfaces	check_interfaces - spong-network module to check for down intefaces via SNMP
check_snmp	check_snmp - spong-network module to check for proper SNMP agent operation
data_sendmsg	data_sendmsg - spong-network module that sends copies of update messages to +other spong-servers
developer-guide	developer-guide - developer's guide to Spong
pre_redirect	pre_redirect - spong-network predata module that redirects update messages +to other spong-servers
spong	spong - character based Spong client interface program
spong-ack	spong-ack - Spong acknowledgment tool
spong-cleanup	spong-cleanup - perform nightly maintenance to the spong database
spong-client	spong-client - report system information to spong server
spong-client-mod-template	spong-client-mod-template - how to create modules for spong-client
spong-intro	Simple System/Network Monitoring - spong v2.0
spong-message	spong-message - send out alerts when there is a problem
spong-message-mod-template	spong-message-mod-template - how to build spong message template
spong-network	spong-network - report network service information to spong server.
spong-network-mod-template	spong-network-mod-template - A sample spong-network check module
spong-server	spong-server - save status information reported by spong programs
spong-server-mod-template	spong-server-mod-template - how to build a spong-server data modules
spong-status	spong-status - send various type of messages to a spong-server
spong.conf	spong.conf - provides configuration information to spong programs.
spong.groups	spong.groups - define groups of spong hosts
spong.hosts	spong.hosts - define hosts and services to monitor
spong.message	spong.message - define rules on how and when to send notifications
spongfaq	spongfaq - frequently asked questions about Spong ($Revision: 1.1 $, $Date: 2005/09/30 07:47:25 $)
todo	<no description>
user-guide	user-guide - a user's guide to using Spong
www-spong	www-spong - display spong system status via the web or general static HTML +pages of system status
www-spong-ack	www-spong-ack - WWW (CGI) based spong acknowledgment tool

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:08 2002 + + + diff --git a/www/docs/todo.html b/www/docs/todo.html new file mode 100755 index 0000000..2cbea59 --- /dev/null +++ b/www/docs/todo.html @@ -0,0 +1,141 @@ + + + + + + +todo + + + + + +

todo

Spong TODO / Wish list +
AUTHOR +

Spong TODO / Wish list

+Here are the features/changes that I and others want to make to spong. They +are in no particular order, If you have any suggestions or comments, send +email to sjohnson@monsters.org. +

+
+Make web interface more configurable: (user selectable background colors/ +method, table shading scheme) (DONE) +
+
+
+Add option to use style sheets on Web Interface. +
+
+
+Client support (spong-client) for NT (DONE) +
+
+
+Server support (spong-server, spong-network, spong-display) support for NT +
+
+
+Make spong-network more parallel, have it perform checks from a pool of +children, that way if a system can not be ping'ed - it will not slow up the rest +of the checks. +
+
+
+Make spong-network check more often on hosts that do not respond on the +first try (DONE) +
+
+
+Add some limited event correlation to spong-network to not report service +problems is a parent router/switch is unreachable. +
+
+
+Optimize the communication between client and server - by pipelining +reports through a single channel and perhaps compressing the data before +sending it. +
+
+
+Make it so that you can click on a host and find out status, history, +configuration (inventory), and statistics. (starting to branch out). (DONE via +configurable ToolBars in Web Interface) +
+
+
+Integrate gstats (statistics collection) program. "spong-stats" (Ed Hill) +
+
+
+Add an inventory/configuration module. "spong-config" (DONE via +configurable ToolBars in Web Interface and packages called SysSymm) +
+
+
+Continue modularizing to move towards Object Oriented as much as possible. +
+
+
+Customizable notify messages in spong-message. (DONE) +
+
+
+Add control ports to spong-client,spong-network, and spong-server to +ultimately allow the programs to be control and configured remotely +
+
+
+Add stats package to record and display status update information in RRD +Tool databases. "spong-rrd" (DONE) +
+
+
+Add SSL to Client/Server protocol for verification and security +
+
+
+Be able to display hosts sorted and sectioned by groups. (DONE) +
+
+
+Add "Sticky" events that can stay around until cleared or time limit expires. +
+
+
+Add event handling API into spong-server for event handler modules +
+
+
+Add summary status type to be able to send summary status messages to other +Spong servers +
+
+
+Add support for multiple Spong-Servers and fail-over capabilities for high +availability (multiple Spong-Servers - DONE) +
+
+
+Purple status (stale messages) checking and notification. +
+

AUTHOR

+Most recently updated on July 28, 2000 +Stephen L Johnson <sjohnson@monsters.org> +

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:07 2002 + + + diff --git a/www/docs/user-guide.html b/www/docs/user-guide.html new file mode 100755 index 0000000..2b94d6f --- /dev/null +++ b/www/docs/user-guide.html @@ -0,0 +1,341 @@ + + + + + + +user-guide + + + + + +

user-guide

NAME +
DESCRIPTION +
SPONG OVERVIEW +
WEB USER INTERFACE +
- Status Colors +
- Display Modes +
+
FRAMES +
- Header Frame +
- Command Frame +
- Display Frame +
+
COMMAND LINE USER INTERFACE +
ACKNOWLEDGMENTS +
AUTHOR +

NAME

+user-guide - a user's guide to using Spong +

DESCRIPTION

+This the user's guide to using spong. It has an overview of the operation of +the whole system and how the user fits into the scheme of things. Spong +acknowledgements, the web-base user interface and the character based +interfaced will be covered in detail. +

SPONG OVERVIEW

WEB USER INTERFACE

+The Spong web display has two different modes that can be configured by the +Administrator: 2 frame or 3 frames. The two modes are essentially the same +from the user's point of view. The 3 frame mode added a header frame at the +top of the windows in addition to the two side by side display frame. +

+The display frames are 2 side by side frames, The left frame is commonly called +the Command frame. It will contains a summary of any hosts that currently have +any problems (i.e. any service that is red.) The right Display frame will +contain various displays that are select from previous displays or the links on +the Command frame. +

Status Colors

+Though out many of the displays the status of a host or a service is expressed +as a color. This will be in the form of a blocks, a strip, or an icons. This is +a list of the colors and their meaning. +

GREEN +: +For a service, green means that it is responding normally, or it is within +normal parameters. For a host, green means that all services are OK and +there are active acknowledgements or over-due service status reported. +
YELLOW +: +For a service, yellow generally means that something minor is wrong and +may need attention, or a parameter is slightly out of bounds. For a host, +yellow mean that one or services are at a warning status. +
RED +: +For a service, red means that is something is critically wrong for a service, +such as a network service not responding or a parameter is radically out +of bounds. For a host, red means that one or more services are at a critical +status. +
PURPLE +: +For a service, purple means it's status report is overdue. The last time +that the service has been updated is too old. this can be due to network +problems or a Spong Client program has stopped for some reason. For +a host, is means that one of more service status reports are over due. +
BLUE +: +For hosts and services, this means that there is an active acknowledgment +on the service or host. While a service is acknowledged, no notifications +will be sent to, but events will still be written to the history log file. +
CLEAR +: +For hosts and service, this meaan that the status is unavailable for some +reason. The usual cause is the host being out of communication. Service checks +used by the spong-network program can be flagged with a +stop_after flag. If a service with the stop_after fails the remaining +checks will be skipped. And all of the remaining checks will have a clear +status. +

Display Modes

+There are two main viewing modes for the Spong web interface +

FRAMES

Header Frame

+In the 3 frame mode of operation this will be displayed across the top +of the web page. This frame is static. It holds a tool bar. +

+The tool bar has controls to switch between the Groups and Hosts view modes +of the two Display frames. The tool bar may also have other controls added +by your the Administrator. +

Command Frame

+The left Command frame is divided 5 or 6 sections from top to bottom: +Title,View Tool Bar, Action Bar, Main Section (problem host list), Host Group +selector and Last Update. The View Tool Bar is only displayed when the Web +display is configured in 2 frame mode. And the Host Group selector will not be +displayed in the Groups view mode. +

Title +

+The section is simple the title Spong and the version number of the server. +

View Tool Bar +

+This has two links, Hosts and Groups, which are used to switch between +the Hosts and Groups viewing modes. This Tool Bar is only displayed is the +Web Interface is configured in 2 frame mode. +

Action Bar +

+The section under the title section is the Command action bar. The Ack link +will bring up the the www-spong-ack manpage CGI program in the Display frame. The page +allows you to display, delete, or create Spong Acknowledgements. The Summary +link brigs up the host summary table of the currently select Host Group(s) in +the Display frame. The <History> link displays the event history for all of +the hosts in the current Host Group. And the Help link will the Spong +HTML documentation. +

Main Section +

+The main section of the Command frame is a list of all of the hosts that +have any problems (e.g. services that are red). If there are +no reported problems then this section will have "No Current Problems" +in green letters. If there are problems then a list of hosts will be displayed +along with name of the services that has the problem. The last date/time +that the service was updated and, is defined. A contact responsible for +the host. +

+The host name is a link that will bring up the full status display +for the host in the Display frame. The problem field under the host +name is a link to the service display page for that host. It will be displayed on +the Display Frame. The updated field is the date and time that the +status of that service updated. The contact field (if present) is a link +that will bring up a custom CGI program that will allow you to send a message +to the people responsible that host. +

Group Section +

+The Host Group section allows to select which group of hosts that you +want to display in the <Summary> and History displays. This +title to the right of the <Group> link is the currently selected Host +Group. Selecting the Group link brings up the Spong Group display +in the Display frame. On top of the page is a list of all of the predefined +host groups defined along with the display name and a summary description +of the group. +

+If you click a group name link, you change the group of hosts +that you are viewing. The web browser window will be redrawn to reflect +the new group of hosts. At the bottom of the <Spong Groups> display +is a section that allows you to select a custom group of hosts to display. +You select all of the hosts that you want to be in your custom group from +the list of hosts. Then click in the Show Hosts button to redraw +the browser window and display the your customized group of hosts. +

+This section will only be displayed in the Hosts view mode. +

Last Update +

+The time stamp section at the bottom is the date and time that the entire +left frame was last updated. If refreshing is allowed by you or your system, +the frame will be automatically reload every $SPONGSLEEP (for spong-server) +seconds. See the section on $SPONGSLEEP in the spong.conf manpage for more information. +

Display Frame

+The right frame is the Display Frame. It is used to display various +informational displays and forms. The default display is the Group Summary. +Most of the sub-pages have an action bar. +

Action Bar +

+The Action Bar on displays is directly under the title at the top +of the page. The Connect to Host link will start a telnet session +to the host if clicked. The Acknowledge Problem link will bring +up the the www-spong-ack manpage CGI program Display. The Host and Service fields will +be filled in (if possible). The Contact Help link (if present) is a link +that will bring up a custom CGI program that will allow you to send a message +to the people responsible that host (see the section on Custom Contacts in the admin-guide manpage for more information). +

Group Summary Display +

+The Group Summary Display is a table that lists the hosts and services of the +current selected group of hosts. The name of the selected group is displayed +at the top of the display. In the Groups view mode, the hosts will be grouped +into separate tables by host groups. +

+Each host is a row in the table with services being the columns of the table. +The current status of each service is a colored block or a icon depending on +how spong-service is configured. The statuses are represented by the color: +RED - critical, YELLOW - warning, GREEN - normal, PURPLE - status is output of +date, BLUE - service has active acknowledgement, CLEAR - status is unavailable, +NOTHING - service is not checked. +

+The host name in the first column is a link to Host Services display the +host. The service names in the first row of the table are links to Help page +for that service. The Help page has a description of the service and the +ramifications if the service is in a warning or critical status. The service +status colored block or icon is a link to the <Service Status> display for +the host/service. +

Host Services Display +

+This display shows most of the available information about the host. The +display is divided into several sections. From top to bottom they are : +Title (Host Name), Action Bar, Overall Status, Acknowledgements, Services +Table, Information, History. +

Title +: +The is the name of the Host being displayed. +
Action Bar +: +The Action Bar is discussed above. +
Overall Status +: +This a bar this displays the current overall status of the host. The over +status is the highest order color of all of the service statuses according +to the following hierarchy: BLUE, RED, YELLOW, PURPLE, GREEN, CLEAR. +
Acknowledgements +: +If there are any Acknowledgements for the host they will be listed here. +Each acknowledgement will have the service that is acknowledged, the expiration +date, and the message. There is a Delete link for each acknowledgement +also which will delete the acknowledgment when clicked. +
Services Table +: +This is a summary table of all of the services that is checked on this host. +The table lists the service name, the current status of the service +(colored-block or icon) , the time (in 23 hour format) of the last update, and +the summary message of message status. The service name and the current status +colored-block/icon are links that will bring of the Service Status display +for the service. +
Information +: +If there is any addition information defined for the host, it will be displayed +in this section. This information is unique to each host. There can be a +description of the functions of the host, embedded image or links to other +information sources. For further information see the the admin-guide manpage. +
History +: +The recent event history of the host will be displayed in this section. +The events are displayed in reverse chronological orders divided into separate +days. Each event has the status color, time (in 24 hour format), host name, +service name, and message summary line of the event. +

Service Status Display +

+This display shows all of the information available for the service/host. It is +divided into several sections: Title (Host Name/Service), Action Bar, Summary +Information, Detailed Information>. +

Title +: +This is the name of the host and service being displayed. +
Action Bar +: +This is discussed above. +
Summary Information +: +This section shows summary information for the service. First is a colored bar +that shows the current status color of the service. See the section on Status Colors elsewhere in this document for +details. Next is the Updated: field which if the date and time of the last +update of the status. The Duration field shows the amount of time that the +service has been in it's current status. And last is the Summary field +which is a one line summary message about the status of the service. +
+
Detailed Information +: +This last section is detailed information about the status of the service. +The type of information depends of the service. For example, for the disk +service it will be the output of the df command showing the mounted +disk partitions and amount of space used on each disk and the for the cpu +service it will be a ps command output showing information about +the top 10 processes using a CPU. +

Acknowledge Problem Display +

+This display is a form generated by the www-spong-ack CGI program. At top of +the form are instructions on how to fill out the form, next will be a list of +all of the current Acknowledgments created for the host. The list includes the +service that was ack'ed, the expiration date of the acknowledgement, and the +message text of the acknowledgment. There is also a Delete link that can be +used to delete the Acknowledgment if clicked. Below this if a form that can be +filled out to create a new Acknowledgment. See the <www-spong-ack> +documentation for more information. +

COMMAND LINE USER INTERFACE

+The command line interface is provided by the spong program. It has all of +the same displays that the Web Interface provides. The spong program is run +with 0, 1 or 2 parameters from a shell prompt. For more information run the +spong program with the --help parameters or see the spong manpage documentation. +

ACKNOWLEDGMENTS

+Spong Acknowlegements are a mechanism that allows the user to notify the +spong-server that they know about the problem and no more notifications need to +be sent. Acknowledgments have a limited life time. After an acknowledgment has +expired, the spong-server will start sending out notifications if necessary. +Acknowledgments are created for a specific host and service, or all services can +be acknowledged by specifying 'all' for the service name. +

AUTHOR

+Stephen L Johnson <sjohnson@monsters.org> +

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:08 2002 + + + diff --git a/www/docs/www-spong-ack.html b/www/docs/www-spong-ack.html new file mode 100644 index 0000000..12cd0f2 --- /dev/null +++ b/www/docs/www-spong-ack.html @@ -0,0 +1,129 @@ + + + + + + +www-spong-ack + + + + + +

www-spong-ack

NAME +
SYNOPSIS +
DESCRIPTION +
- Theory of Operation +
+
CONFIGURATION +
- Configuration Files +
- Configuration Variables +
+
FILES +
DEPENDENCIES +
BUGS +
SEE ALSO +
AUTHOR +
HISTORY +

NAME

+www-spong-ack - WWW (CGI) based spong acknowledgment tool +

SYNOPSIS

+http://spong-server.my-inc.com/spong/www-spong-ack +

DESCRIPTION

+Then a spong event occurs (or will occur), you can use this tool to acknowledge +that your know there is a problem. You can provide text that will be seen by +others looking at the event (via a spong display program). You can specify a +time limit that the problem will occur. If a problem has been acknowledged, +you will no longer receive notifications of the problem, and the spong display +programs will show the of the service(s) as "blue". +

Theory of Operation

+The www-spong-ack program is designed to interact with the the www-spong manpage +Spong display program, but it the program can be used if it is invoked directly. +

+When the program is initially invoked it will list all of the acknowledgments at +the top of the page in the "Current Acknowledgments" section. The host/service +and the expiration date/time of the acks are displayed. A Delete link is +provided for every ack. that will delete that particular ack. when selected. +

+Below in the "New Acknowledgment" section is a form form for creating a new +acknowledgment. The host name is selected from the drop-down box. The service(s) +to be acknowledged is entered in service field. The duration of the event is +entered in one of several formats into the duration field. Your e-mail address +should be entered into the e-mail address field. It is only used to show who +created the ack. And a message about the acknowledgement can be entered. Once +all of the information is entered, press the 'Create' button to create the +acknowledgement. +

CONFIGURATION

Configuration Files

+spong-cleanup reads the standard spong.conf and spong.conf.<host> +configuration files. +

Configuration Variables

$SPONGSERVER +: +The host that at least the the spong-server manpage and the spong-message manpage +programs are running on. Typically the the spong-network manpage program runs on that +host as well. +
$SPONG_UPDATE_PORT +: +This variable defines the port that the the spong-server manpage update process listens +on. If this variable is not defined on the $SPONGSERVER host, the +the spong-server manpage update process will not be started. The default value is 1998. +

FILES

+SPONGHOME/etc/spong.conf, SPONGHOME/etc/spong.conf.<host> +

DEPENDENCIES

+Perl v5.005_03 or greater is required. +

+A working web server that can run CGI programs. +

BUGS

+No know bugs. +

AUTHOR

+Stephen L Johnson <sjohnson@monsters.org> +

HISTORY

+[Top] +Generated by Pod::HTML 0.44 on Thu Jun 6 17:59:08 2002 + + + diff --git a/www/docs/www-spong.html b/www/docs/www-spong.html new file mode 100755 index 0000000..6c8804b --- /dev/null +++ b/www/docs/www-spong.html @@ -0,0 +1,206 @@ + + + + + + +www-spong + + + + + +

www-spong

NAME +
SYNOPSIS +
DESCRIPTION +
OPTIONS +
CONFIGURATION +
- Configuration Files +
- Configuration Variables +
+
FILES +
DEPENDENCIES +
BUGS +
SEE ALSO +
AUTHOR +
HISTORY +

NAME

+www-spong - display spong system status via the web or general static HTML +pages of system status +

SYNOPSIS

DESCRIPTION

+The www-spong program interfaces with the spong-server to display the +collected information in HTML format. www-spong can be run in two modes: as +a CGI program and from the command line. +

+When run as a CGI program it does not have to loaded onto the same machine that +spong-server is running. It queries the spong-server through it's query port. +it will display information via a web page that reloads itself at regular +intervals. When run with no parameters it created a page with two or three +frames. In tree frames mode there will be a top title frame spanning the entire +page that has an action bar to switch views. The remain frames are displayed +below. The left frame displays a summary of systems along with their +associated problems (services that are red). The right panel is a table that +lists the hosts and services, and the current status is a colored block or an +icon depending on how spong-server is configured. For further information on +how to use the web interface see <Users Guide|user-guide>. +

+When run from a command line, www-spong generates HTML pages that are printed +to the console. This mode can be used to generate static HTML pages. If +www-spong is run without any parameters a page that contains a summary display +for all hosts is generated. +

OPTIONS

--summary [hostlist] +: +Summarize the status of hosts, in hostlist, in a table that lists +the hosts and services, and the current status is a colored block or an +icon depending on how spong-server is configured. If hostlist if not specified +all hosts defined in spong.hosts are displayed. +
--grp-summary +: +Summary the status of all by Host Groups defined in the the spong.groups manpage file. +Each Host Group is displayed in a table that lists the hosts and services, and +the current status is a colored block or an icon depending on how spong-server +is configured. +
--problems [hostlist] +: +Shows a summary of all the problems (services that are red) for the all +the hosts in hostlist. If hostlist is not specified, all hosts defined +in spong.hosts are displayed. +
--grp-problems +: +Shows a summary of all of the problems (services that are red) for all Host Groups +defined in the the spong.groups manpage file. +
--history [hostlist] +: +Show history information for the the list of hosts in hostlist. If host +list is not specified, all hosts defined in spong.hosts are displayed. +
--host host +: +Shows all information available for the given host. +
--services host +: +Shows detailed service information for the given host. +
+
--stats host +: +Show statistical information for the given host. +
--config host +: +Shows configuration information for the given host. +
--info host +: +Shows admin supplied text for the given host. +
--service host:service +: +Shows detailed information for the given host/service. +
--brief +: +Display output in a brief format. +
--standard +: +Display output in standard format (the default). +
--full +: +Display the maximum amount of information possible. +

$SPONGSERVER +: +The make of the server that spong-server is running on. +
$SPONG_QUERY_PORT +: +The port number that spong-server listens at for database queries. +
$SPONGSLEEP{'www-spong'} or $SPONGSLEEP{'default'} +: +The delay in seconds between display reloads. +
$WWWFRAMES +: +Number of frames to use for the display (can be 2 or 3). +
$TIMEFMTNOSEC and $DATEFMT +: +Date and time formats. +

FILES

spong.conf +: +Configuration file. This contains variables that detail spong and OS specific +definitions used by spong-server. +