From 58a1b9c46db2748eeb7c51d9d121000395629a12 Mon Sep 17 00:00:00 2001 From: Stephen L Johnson Date: Wed, 17 Nov 1999 05:14:04 +0000 Subject: [PATCH] Initial revision --- www/docs/admin-guide.html | 260 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100755 www/docs/admin-guide.html diff --git a/www/docs/admin-guide.html b/www/docs/admin-guide.html new file mode 100755 index 0000000..3a4ada2 --- /dev/null +++ b/www/docs/admin-guide.html @@ -0,0 +1,260 @@ + + + + + + admin-guide + + + +

+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 test to see is the server 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 just the spong-client +and a spong.conf file and make sure they start up when your system is rebooted. +

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

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