From: Stephen L Johnson Date: Thu, 16 Dec 1999 06:35:43 +0000 (+0000) Subject: Documentation update on spong-server data modules. X-Git-Tag: spong-2_6-beta8~2 X-Git-Url: http://git.etc.gen.nz/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2a0751785cd4070fdbbcfa54b450560ca7a986f7;p=spong.git Documentation update on spong-server data modules. --- diff --git a/www/docs/developer-guide.html b/www/docs/developer-guide.html index 385028d..49bf754 100755 --- a/www/docs/developer-guide.html +++ b/www/docs/developer-guide.html @@ -87,12 +87,31 @@ or the detailed reponses of network checks.

MODULES

-Both spong-client, spong-network and spong-message use routines which are +spong-client, spong-network, spong-message and spong-server use routines which are modules. When the programs are initializating, they determine which modules are going to be required. The programs then go out and load each of the modules from the library directory. When the modules are loaded they register themself with the plugins registery. The plugin registry is the mechanism that the client programs keep track of the modules into order to run them. + +

SERVER MODULESSpong-server has a hook that allows external programs access to the incoming +status updates coming from Spong client programs. The hook takes the form of +Server Data modules which are called after spong-server stores the status +update in it's database. + +spong-server passes all of the information of the update message in addition +to the current event status duration to the Data Module. The modules should +do any processing that they need to do in as short a time as possible. The +spong-server update process is single threaded. Any excessive delays in +in return can cause pending updates to time out. + +Debugging messages and error messages can be printed by using the +&main::debug() and &main::error() functions respectively. If the module +develops a fatal error, it should terminate using the die() or croak() +functions depending on ones preference. Modules should just return upon a +successful invocation. +

CLIENT MODULES

Client modules define checks which are to be done on the host that the spong-client program is running on. The module's check function is called @@ -263,6 +282,11 @@ following the appropriate template from below.

spong-message module tempage

+ +
+spong-server data module template +
+ Then place your template module file into the appropirate directory below.
@@ -274,6 +298,9 @@ spong-nework - LIBDIR/Spong/Network/plugins
spong-message - LIBDIR/Spong/Message/plugins
+ +
+spong-server - LIBDIR/Spong/plugins

Then test your modules by running the program with the --debug option to if it is operating properly. diff --git a/www/docs/spong-server.html b/www/docs/spong-server.html index 9f984f9..d563e10 100755 --- a/www/docs/spong-server.html +++ b/www/docs/spong-server.html @@ -1,215 +1,191 @@ -spong-server - -
- -
- -NAME -
-spong-server - save status information reported by spong programs -
- -
- -SYNOPSIS -
-spong-server [--debug] [--kill|--restart] [config_file] -
- -
- -DESCRIPTION -
-The spong-server program starts up and listens to status reports from various -spong clients (specifically the spong-network and various spong-client programs -running). It takes the information reported by the various spong clients and -does the following: -
-
-
Each time a message comes in, a child process is forked off to handle the above -tasks, while the main spong-server program goes back to waiting for more -status reports. -
You should start this program in your system startup file, and it should be -running constantly. If you provide the --debug flag, then debugging -information will be printed to stdout, otherwise output will only be -produced if there is a problem. -
If you provide the --restart flag, a signal will be sent to the spong-server -process that is currently running that will cause it to reload it's -configuration files. If you provide the --kill flag, a signal will be sent to -the running spong-server process causing it to exit. -
- -
- -CONFIGURATION -
-The configuration of the spong-server program is two fold, the first part is -the -/usr/local/etc/spong/spong.hosts - file. This file lists the host that are being -monitored by the spong-network and spong-client programs. Only status -information on hosts in the spong.hosts file are considered valid and saved. -
The second part of the configuration is the -/usr/local/etc/spong/spong.conf - file which -define some specific variables that you probably don't need to override. By -default the spong.conf file is read on startup. You can specify an alternate -config file via a command line option and it will read that file instead. If -you change values in the configuration file you will need to restart this -program for those changes to be re-read. -
After reading the configuration file that you specify (or the default), it then -reads the /usr/local/etc/spong/spong.conf.[host] file where [host] is the hostname of -the machine that you are running on. Since these configuration files are just -standard perl code that gets imported, the variables that you define in the -host specific config file will take precedence over the standard configuration -settings. -
Here are a list of variables in the spong.conf file that are applicable to the -spong-server program: -
-
-
- - - - -$SEND_MESSAGE - -
-
- -$SEND_MESSAGE - defines when spong-message is called by spong-server. This -variable can contain one of three valid values. If it is ``RED'', then -spong-message is called for every time a system or service reports a problem. -If its value is ``CHANGE'', then spong-message is only called when there is a -change of state (going from green to red, and then again going from red to -green). If its value is ``NONE'', then spong-message is never called. -
-
-$SPONGPORT, $SPONGSTATUS, $SPONGHISTORY, $SPONGNOTES
-The port number that the server should be listening at, and some directory -locations where status information, history information, and host specific -documentation are kept. -
-
-
- -
- -FILES -
-
-
-
- - - - -/usr/local/etc/spong/spong.conf - -
-
-Configuration file. This contains variables that detail spong and OS specific -definitions used by spong-server. See spong.conf for additional -documentation. -
-
- - - - -/usr/local/etc/spong/spong.hosts - -
-
-Host and human configuration file. This defines what hosts you are monitoring, -and what human you should contact if there is a problem. See spong.hosts -for additional documentation. -
-
- - - - -/local/www/docs/spong/status/ - -
-
-The directory where status information is saved. The files in this directory -should be readable by your web server as spong-display using this information -to generate the web pages that it displays. -
-
- - - - -/local/www/docs/spong/history/ - -
-
-The directory where history information is stored. The files in this directory -should also be readable by your web server. -
-
- - - - -/local/www/docs/spong/notes/ - -
-
-The directory where host specific information is stored. For each host that -you monitor, if there is a file in this directory with the same name as that -host then that file will be displayed by spong-display when the user clicks on -a specific host. -
-
-
- -
- -DEPENDENCIES -
-Perl v5.003 or greater is required. -
- -
- -BUGS -
-It is not sufficiently paranoid. It should probably perform more strict -authentication to protect against bogus data. -
- -
- -SEE ALSO -
-the spong-network manpage -, the spong-client manpage -, the spong-display manpage -, the spong-message manpage -, -spong.hosts, spong.conf -
- -
- -AUTHOR -
-Ed Hill (ed-hill@uiowa.edu), Unix System Administrator, The University of Iowa -
Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong). -
- - + + + + + + spong-server + + + +
+
+NAME
+spong-server - save status information reported by spong programs +
+
+
+SYNOPSIS
+spong-server [--debug] [--kill|--restart] [config_file] +
+
+
+DESCRIPTION
+The spong-server program starts up and listens to status reports from various +spong clients (specifically the spong-network and various spong-client +programs running). It takes the information reported by the various spong +clients and does the following: +
+ * Check for valid messages, and discards any invalid ones. + + * If the message is something worth notifying someone about, it calls + + the spong-message program and lets it determine how/if to contact + + someone about the problem. + + * Check to see if the color of this message is different then it + + used to be, and if so generate a history item indicating the change. + + * Save the information in the $SPONGSTATUS directory. + + + + + +
+Each time a message comes in, a child process is forked off to handle the +above tasks, while the main spong-server program goes back to waiting for +more status reports. +
You should start this program in your system startup file, and it should +be running constantly. If you provide the --debug flag, then debugging +information will be printed to stdout, otherwise output will only be produced +if there is a problem. +
If you provide the --restart flag, a signal will be sent to the spong-server +process that is currently running that will cause it to reload it's configuration +files. If you provide the --kill flag, a signal will be sent to the running +spong-server process causing it to exit. +
+
+
+CONFIGURATION
+The configuration of the spong-server program is two fold, the first part +is the /usr/local/etc/spong/spong.hosts +file. This file lists the host that are being monitored by the spong-network +and spong-client programs. Only status information on hosts in the spong.hosts +file are considered valid and saved. +
The second part of the configuration is the /usr/local/etc/spong/spong.conf +file which define some specific variables that you probably don't need +to override. By default the spong.conf file is read on startup. You can +specify an alternate config file via a command line option and it will +read that file instead. If you change values in the configuration file +you will need to restart this program for those changes to be re-read. +
After reading the configuration file that you specify (or the default), +it then reads the /usr/local/etc/spong/spong.conf.[host] file where +[host] is the hostname of the machine that you are running on. Since these +configuration files are just standard perl code that gets imported, the +variables that you define in the host specific config file will take precedence +over the standard configuration settings. +
Here are a list of variables in the spong.conf file that are applicable +to the spong-server program: +
+
+$SEND_MESSAGE
+ +
+$SEND_MESSAGE +defines when spong-message is called by spong-server. This variable can +contain one of three valid values. If it is ``RED'', then spong-message +is called for every time a system or service reports a problem. If its +value is ``CHANGE'', then spong-message is only called when there is a +change of state (going from green to red, and then again going from red +to +green). If its value is ``NONE'', then spong-message is never called.
+ +
+$SPONGPORT, $SPONGSTATUS, $SPONGHISTORY, $SPONGNOTES
+ +
+ The port number that the server should be listening at, and some +directory locations where status information, history information, and +host specific documentation are kept.
+ +
+
+
+DATA MODULES
+spong-server has a plugin and registry mechanism what provides a +hook for access incoming status updates. Any data plugin modules placed +into the SPONGHOME/lib/Spong/plugins directory will be loaded upon +spong-server initialization. As each module it registers itself +with the plugin registry (see the Developer +Guide). There are no standard Server Data Modules. There are some sample +modules in the contrib/plugins/spong-server directory of the Spong +distribution. For more information in developing a Server Data Modules +see the spong-server +module template documenation.
+ +
+
+FILES
+ +
+
+/usr/local/etc/spong/spong.conf
+ +
+Configuration file. This contains variables that detail spong and OS specific +definitions used by spong-server. See spong.conf for additional +documentation.
+ +
+/usr/local/etc/spong/spong.hosts
+ +
+Host and human configuration file. This defines what hosts you are monitoring, +and what human you should contact if there is a problem. See spong.hosts +for additional documentation.
+ +
+/local/www/docs/spong/status/
+ +
+The directory where status information is saved. The files in this directory +should be readable by your web server as spong-display using this information +to generate the web pages that it displays.
+ +
+/local/www/docs/spong/history/
+ +
+The directory where history information is stored. The files in this directory +should also be readable by your web server.
+ +
+/local/www/docs/spong/notes/
+ +
+The directory where host specific information is stored. For each host +that you monitor, if there is a file in this directory with the same name +as that host then that file will be displayed by spong-display when the +user clicks on a specific host.
+ +
+

+ +
+
+DEPENDENCIES
+Perl v5.003 or greater is required. +
+
+
+BUGS
+It is not sufficiently paranoid. It should probably perform more strict +authentication to protect against bogus data. +
+
+
+SEE ALSO
+the spong-network manpage , the spong-client manpage , the +spong-display manpage , the spong-message manpage , spong.hosts, +spong.conf +
+
+
+AUTHOR
+Ed Hill (ed-hill@uiowa.edu), Unix +System Administrator, The University of Iowa +
Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong). + +