From: Stephen L Johnson Date: Thu, 16 Dec 1999 07:34:37 +0000 (+0000) Subject: Documentation updates. X-Git-Tag: spong-2_6-beta8^0 X-Git-Url: http://git.etc.gen.nz/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8ce0a370ea07b7632c30a86d7c9307ca6812677d;p=spong.git Documentation updates. --- diff --git a/www/docs/spong-2_0.html b/www/docs/spong-2_0.html index fb386b9..672dd73 100755 --- a/www/docs/spong-2_0.html +++ b/www/docs/spong-2_0.html @@ -1,399 +1,374 @@ - -Simple System/Network Monitoring - spong v2.0 - - - -

Simple System/Network Monitoring - spong v2.0

-
- -

Description

-This is a simple system monitoring package called spong. It has the -following features: -

- -

- -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 -todo 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 is currently at version 2.0. If you are using an older version and want -to see what's new in version 2.0, please look at the -bottom on this page.

- -

Availability

- -Perl is require to run spong. If you don't have Perl installed you can -retrieve it from the CPAN (http://www.perl.com/CPAN/) archive, 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:

- -

- -You can retrieve the latest version of spong from my machine at:

- -

- -You can see some screen shots of spong in action (note these are just examples -of HTML that is produced - not the actual programming running - most people -don't want this level of system information public to the world (if they can -help it).

- -

-

This distribution contain the spong source, documentation, and gif images. -

- -

Notification

- -I have sent up a mailing list that I will post to when I have released a new -version of spong. Anyone can join this list, but the traffic will be only one -way (me posting information about new-releases). If enough people are -interested in creating a list for discussion spong in general, I will set one -up at that time. I try to answer any questions that are sent to me.

- -To join the spong-announce mailing list, send a message to -majordomo@strobe.weeg.uiowa.edu with the sentence:

- -

- -in the body of the message. To have yourself removed from the -spong-announce mailing list, send a message to -majordomo@strobe.weeg.uiowa.edu with the sentence unsubscribe -spong-announce in the body of the message.

- -The traffic on the list will be very light - about 1 message per month at -most.

- - -

Dependencies

- -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). I will try to make sure the scripts run -under NT when I have better access to an NT machine.

- - -

Installation

- -To build and install the spong server do the following on the machine running -your web server.

- -

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

    - -

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

    - -

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

    - -

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

    - -

  5. Now edit the spong.conf, and spong.hosts 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.

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

- -

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 HTML format (the old Perl pod format just -didn't do all that I wanted). It is located in the docs directory and is self -contained (the links will still work if you move it), so you should be able to -copy it to whatever location that you want.

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

- -

-
Overview -
Just that, gives a quick 5 minute overview of what spong is and what it can -do.

- -

User's 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 whats 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

- 

-    www:

-      gifs:                   various icons used by spong-display

-

-
- -

Licensing

- -Copyright 1997, Ed Hill - The University of Iowa

- -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 ed-hill@uiowa.edu, and I will mail you a -copy.

- - -

Changes between v2.0 and v1.1

- -The most significant change in version 2.0 is a rewrite and redesign of spong -internals to move towards a more modular and OO framework. The first version -of spong was just a port of the BB program to perl with some of my own -modifications, this version contains a significant rewrite of the spong-server -program to make it more object oriented and extensible. I believe this puts -spong in a better position to maintain (by me) and extend (by you). - -The spong-client and spong-network programs are still pretty much the same - -Other then the redesign issue, this release has a few new features and -programs, and some bug fixes (as well as some new introductions I'm sure). The -most significant changes are:

- -

- -You can see a list of features that I hope to add to spong at:

- -

- - -

History

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

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

- -

Known Problems in v2.0

- -Here are a list of problems, and possible fixes that have been reported for -version 2.0. 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.

- -

- -

Author

- -Ported and currently maintained by: -

- -Ed Hill (ed-hill@uiowa.edu)
-Internet Software Developer at -The University of Iowa

- -

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

-

-Most recently updated on Aug 1, 1997 by -Ed Hill -(ed-hill@uiowa.edu) - - - + + + + + + Simple System/Network Monitoring - spong v2.0 + + + +

+Simple System/Network Monitoring - spong v2.0

+ +
+

+Description

+This is a simple system monitoring package called spong. It has +the following features: + +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 todo 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 is currently at version 2.6. If you are using an older version and +want to see what's new in version 2.6, please +look at the bottom on this page. +
  +
  +

+Availability

+Perl is require to run spong. If you don't have Perl installed you can +retrieve it from the CPAN (http://www.perl.com/CPAN/) +archive, 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: +
  +
  + +You can retrieve the latest version of spong from my machine at: +
  +
  + +This distribution contain the spong source, documentation, and gif images. +

+Notification

+I have sent up a mailing list that is for spong discussion, help and annoucements. +The mailing list open to anyone. I am on the list and I endevour to answer +all questions submitted to the list. +

 To join the spong mailing list, send a message to spong-request@monsters.org +with the sentence: +
  +

+in the body of the message. To have yourself removed from the spong-announce +mailing list, send a message to spong-request@monsters.org +with the sentence unsubscribe in the body of the message. +

 You can also visit the Spong +mailing list web page to subscribe or view the mailing list archives. +
  +

+Dependencies

+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 HTML format (the old Perl pod +format just didn't do all that I wanted). It is located in the docs directory +and is self contained (the links will still work if you move it), so you +should be able to copy it to whatever location that you want. +

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

+
+FAQ
+ +
+Frequently Asked Questions by users and their answers.
+ +
  +

  +
  +
  +

+User's 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 whats 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.&ltos>         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
+ +
+
+    www:
+ +
      docs:
+
+      <*>.html                documentation for the above files 
+
+      gifs:                   various icons used by spong-display
+
+
+
+
+ +

+Licensing

+Copyright 1999, Stephen Johnson +

 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 can be found at: +
http://monsters.org/pub/spong/CHANGES
+You can see a list of features that I hope to add to spong at: + + +

+History

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Version 2.6Notification 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 releae 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 routnie 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

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

The about acknowledgements are from Ed Hill. 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.  +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. +
  +
  +

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

+Author

+Ported  by: +

Ed Hill (ed-hill@uiowa.edu) +
Internet Software Developer at The +University of Iowa +

Currently maintained by: +
Stephen L Johnson (sjohnson@monsters.org) +

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

+

Most recently updated on Dec 15, 1997 by Stephen +L Johnson (sjohnson@monsters.org) + + diff --git a/www/docs/todo.html b/www/docs/todo.html index 594602d..58430ed 100755 --- a/www/docs/todo.html +++ b/www/docs/todo.html @@ -28,6 +28,9 @@ of the checks.
  • Make spong-network check more often on hosts that do not respond on the first try +
  • Add some limited event correlation to spong-network to not report service +problems is a parent router/swith is unreachable. +
  • Optimize the communication between client and server - by pipelining reports through a single channel and perhaps compressing the data before sending it. @@ -35,7 +38,7 @@ 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). -
  • Integrate my gstats (statistics collection) program. "spong-stats" (Ed Hill) +
  • Integrate gstats (statistics collection) program. "spong-stats" (Ed Hill)
  • Add an inventory/configuration module. "spong-config"
  • Continue modularizing to move towards Object Oriented as much as possible. @@ -43,9 +46,12 @@ configuration (inventory), and statistics. (starting to branch out).
  • 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 inforation in +RRD Tool databases. "spong-rrd" +
    -Most recently updated on Dec. 6, 1999 by +Most recently updated on Dec. 15, 1999 by Stephen L Johnson (sjohnson@monsters.org)