--- /dev/null
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <meta name="GENERATOR" content="Mozilla/4.61 [en] (X11; U; Linux 2.2.12-20 i686) [Netscape]">
+ <title>admin-guide</title>
+</head>
+<body>
+
+<h1>
+Spong Administrator's Guide</h1>
+
+<hr WIDTH="100%">
+<h1>
+Installation</h1>
+
+<h2>
+Installation - Server</h2>
+To build and install the spong server do the following on the machine running
+your web server.
+<ol>
+<li>
+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.</li>
+
+<br>
+<li>
+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.</li>
+
+<br>
+<li>
+Make sure you are in the directory that you unpacked spong in and type:
+<tt>./build
+<os></tt> where <os> is the name corresponding to your operating
+system. You can type <tt>./build help</tt> to generate a list of valid
+operating system strings.</li>
+
+<p><br> 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.
+<br>
+<li>
+Now, type <tt>./build install</tt>. Note that the install process makes
+no assumptions about what user you want to run spong as (you <b>don't</b>
+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).</li>
+
+<br>
+<li>
+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.</li>
+</ol>
+
+<p><br>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.
+<p><b>NOTE - HOSTNAMES:</b> 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.
+<p>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 <b>gethost-test</b> from in the "utils" directory of the Spong
+distribution. Just run it from a command line by entering <i>perl gethost-test.</i>
+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.
+<br>
+<h2>
+Installation - Client</h2>
+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.
+<p>
+<hr WIDTH="100%">
+<h2>
+Debugging Problems</h2>
+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.
+<br>
+<dt>
+<b>spong-server</b></dt>
+
+<dd>
+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 <i>query</i> processing will print out all of the database
+queries with the type of data requested and in what format. The <i>spong
+update</i> and <i>Big Brother update</i> process will print out host/service/color
+of every status message that is received.</dd>
+
+<br>
+<dt>
+<b>spong-client</b></dt>
+
+<dd>
+spong-client will print out the check that is being performed along with
+the status and the summary message.</dd>
+
+<dt>
+</dt>
+
+<dt>
+<b>spong-network</b></dt>
+
+<dd>
+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.</dd>
+
+<dt>
+</dt>
+
+<dt>
+<b>spong-message</b></dt>
+
+<dd>
+spong-message can be tested outside of spong-server to test your notification
+configurations. Your run spong-message with the following parameters:</dd>
+
+<dd>
+</dd>
+
+<dd>
+spong-message --debug color host service time "Summary message" [duration]</dd>
+
+<dd>
+</dd>
+
+<dd>
+where</dd>
+
+<dd>
+ 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.</dd>
+
+<dd>
+ duration - This is the current of the current status in seconds.
+It is an optional parameter. It defaults to 0.</dd>
+
+<dd>
+</dd>
+
+<dd>
+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.</dd>
+
+<p><br>
+<hr WIDTH="100%">
+<h2>
+<a NAME="header-footer"></a>Customizing Web Pages</h2>
+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 <b>$IWWW</b>
+variable from the <i>build</i> program) and named header.html or footer.html,
+respectively.
+<p>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 "<b>!!WWWSHOW!!</b>/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.
+<p><b>Note:</b> 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.)
+<br>
+<h2>
+<a NAME="info-notes"></a>Expanded Host Status Web Pages</h2>
+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. <b><a href="spong_conf.html#spongdb">$SPONGDB</a></b>/hostname/info/
+). Then you place the documentation files that will displayed into that
+directory. <i><a href="spong-server.html">spong-server</a></i> looks for
+the the following files:
+<p><b>$SPONGDB</b>/hostname/info/info.txt
+<br><b>$SPONGDB</b>/hostname/info/info.html
+<p><b>$SPONGDB</b>/hostname/info/info.brief.txt
+<br><b>$SPONGDB</b>/hostname/info/info.standard.txt
+<br><b>$SPONGDB</b>/hostname/info/info.full.txt
+<p><b>$SPONGDB</b>/hostname/info/info.brief.html
+<br><b>$SPONGDB</b>/hostname/info/info.standard.html
+<br><b>$SPONGDB</b>/hostname/info/info.full.html
+<p><i><a href="spong-server.html">spong-server</a></i> 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, <i><a href="spong-server.html">spong-server
+</a></i>will
+look for a info.txt or info.html file and then display that file as a default.
+<p>The .txt files are used with text mode displays like those generated
+by the <i><a href="spong.html">spong</a></i> 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.
+<br>
+<h2>
+<a NAME="custom-contacts"></a>Smart "Contact Staff" Links</h2>
+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.
+<p>The "Contact Staff" link's URL consists of two parts. The first part
+is the $<b><a href="spong_conf.html#wwwcontact">WWWCONTACT</a></b> from
+the <a href="spong_conf.html">spong.conf</a> 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: <b>host</b> and <b>message</b> respectively.
+<p>The <b><a href="spong_conf.html#wwwcontact">$WWWCONTACT</a></b> CGI
+program needs to handle two form variables (<b>host</b> and <b>message</b>)
+and place them into a form for the user to fill out. A TEXT field should
+be used to the <b>host</b> 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.
+<br>
+<h2>
+<a NAME="autorefresh"></a>WWW_REFRESH LOGIC</h2>
+The default of the spong-server is to not allow auto-refreshes if <b><a href="spong_conf.html#www-refresh-allow">@WWW_REFRESH_ALLOW</a></b>
+and <b><a href="spong_conf.html#www-refresh-deny">@WWW_REFRESH_DENY</a></b>
+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.
+<p>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.
+<br>
+</body>
+</html>
projects / spong.git / commitdiff