[Table of Contents][Index]



admin-guide - Spong Administrator's Guide


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


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.

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 the Admininistration Guide|admin-guide entry elsewhere in this document.

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

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.


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.


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, you need to set $WWWSPONG to '/spong/cgi-bin/www-spong'. See also the section on Spong CGI Directory elsewhere in this document.
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, you need to set $WWWSPONG to '/spong/cgi-bin/www-spong-ack'. See also
 the section on Spong CGI Directory elsewhere in this document.
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, then $WWWGIF is set to '/spong/gifs'. See also the section on Spong HTML Directory elsewhere in this document.
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.
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 on an Apache web server, use this configuration line:
  Alias /spong/ /usr/local/spong/www/


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.


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 will print out the check that is being performed along with the status and the summary message.


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


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.


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 entry elsewhere in this document looks for the the following files:

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 entry elsewhere in this document 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.


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 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 (, auto-refresh would not be enabled because 'fred' is in the I@<WWW_REFRESH_DENY> list.


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 the spong-network|spong-network entry elsewhere in this document program.

At present there is only one meta-service: noping. the spong-network|spong-network entry elsewhere in this document 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

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:

   '' => { 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.


the spong-server entry elsewhere in this document, the www-spong entry elsewhere in this document, the spong.conf manpage


Stephen L Johnson <>

[Top] Generated by Pod::HTML 0.43 on Wed Jun 13 11:17:40 2001