Spong Administrator's Guide
Installation
Installation - Server
To build and install the spong server do the following on the machine running
your web server.
-
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 SPONGSTATUS directory that you defined in the spong.conf
file.
NOTE - HOSTNAMES: Part of spong-server's status message authentification
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 add in this check 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.
Installation - Client
For each client machine you will need to install the the package just like a
te 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 spong.conf file.
If your 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 mechamism your would
normally use. Just be sure the Spong installation directory into the same
location as the original client.
Debugging Problems
The general way to debug Spong programs is to use the --debug parameter.
This force the program to run in the fore-ground, if it backgrounds itself,
and the program will print out a lot of debugging statements.
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.
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 is 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" [duration]
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.
duration - This is the current of the current status in seconds.
It is an optional parameter. It defaults to 0.
spong-mesage will print out the current rule number(starting with 0), and
then 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 testing it.
Customizing Web Pages
Spong have a feature that allows users to customize some aspects of the
Spong web pages. If a header and/or footer template file exists,
then 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 specifiy 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 subsitiution 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 Web Pages
This feature is one of Spong's best kept secrets. You can create additional
information files that will be displayed on all host status displays. 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. spong-server 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
spong-server first looks for
a info.brief, info.standard or info.full file depending on the type
of display (brief, stanard or brief; 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 command. The .html files are
used by the html mode displays. The .html files can contain html code,
URLs, embeded graphics, Javascript, or anything that you display on a web
page.
Smart "Contact Staff" Links
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 hosts and a message
which contains all of the current problems that system currently has.
The "Contact Staff" link's URL consists of two parts. The first part
is the $WWWCONTACT from
the spong.conf configuration file. It contains
the URL to your contact staff CGI program that your 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 place them into 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 field that you need
into order to send your messages.
Customized Action Bar
The Action Bar of the Host and Service Status Displays (see the
User Guide for more details) can be customized
with the $WWW_ACTIONBAR_CUSTOM
configuration parameter. Any HTML code defined in this parameter
will be included on the end of the Action Bars.
This parameter is preprocessed
with eval before the contents are printed. This allows you to
include complex perl variables or perl code. Because of the eval you
should use single quotes to enclose the contents of this parameter. This
will prevent premature evaluation of perl variables before the preprocessing.
If your do not need this customization, just leave
$WWW_ACTIONBAR_CUSTOM undefined. Nothing will be added to the Action Bars.
WWW_REFRESH LOGIC
The default of the spong-server is to not allow auto-refreshes if @WWW_REFRESH_ALLOW
and @WWW_REFRESH_DENY
variables are empty. The spong-server the matched the REMOTE_ADDR,
REMOTE_HOST, and REMOTE_USER field sagainst the list 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 REFRESH_ALLOW contains[ 'joe', '.*-support', '^192.168.12.*',
'noc-display' ] and REFRESH_DENY contains ['bill','mary']. If a web browers
on a machine at ip address 192.168.12.143 was displaying the spong-server
web pages, the auto-refresh would be enables because it matches the '^192.168.12.*'
expression of REFRESH_ALLOW. But if the user was fred at the same machine
(192.168.12.143), access the web pages auto-refresh would not be enables
because 'fred' is in the RERESH_DENY list.