From fe7a347f2b7a29a4389964032b5d6b73ad837951 Mon Sep 17 00:00:00 2001 From: Stephen L Johnson Date: Mon, 8 Nov 1999 22:36:02 +0000 Subject: [PATCH] Initial import --- www/docs/developer-guide.html | 281 ++++++++++++++++++++++++++++++++++ 1 file changed, 281 insertions(+) create mode 100755 www/docs/developer-guide.html diff --git a/www/docs/developer-guide.html b/www/docs/developer-guide.html new file mode 100755 index 0000000..385028d --- /dev/null +++ b/www/docs/developer-guide.html @@ -0,0 +1,281 @@ + + + + + + + developer-guide + + + +

+NAME

+developer-guide - developer's guild to Spong +
+
+

+DESCRIPTION

+This is the developer guild to Spong. The man page documents the inner +works of the client and server programs. It also describes the plugins +mechanism of the spong-client and +spong-network, so that new check +modules can be developed for this programs. +
  +

+PROTOCOLS

+This section deals with the low level communucation protocols that the +clients use to talk with the spong-server. +The spong and Big Brothers protocols almost identical. they vary only in +the data format. +

SPONG PROTOCOL +
The spong-server listens in on port 1998 for status updates +from clients. After a socket has been opens the client sends a message +with the following format: +

command  host  service  color  time  +summary (\n) +
detailed status message line 1 (\n) +
detailed status message line 2 (\n) +
   ... +
detailed status message line n (\n)
+Where: +
command - The command being sent to the spong server indicating +a type of update message or a change in operating status of the client. +At present the only command defined is status which inidicates a +service status update message. +
host - The fully qualified domain name of the host the message +is for. +
service - The name of the service that the update message is +for. +
color - The status color of the service (green - ok, yellow +- warning, red - alert). +
time - The date/time of the update message in epoch time format +(i.e. the number of seconds since 01/01/70, 00:00 AM) +
summary - The status summary message field. +
detailed status message - The remained lines of the message +which will be the detailed information of the status. Typically it can +be the output of the df command or the top processes by CPU utilization +or the detailed reponses of network checks. +
  +

BIG BROTHER PROTOCOL +
The spong-server listens in on port 1984 for status Big Brother +client updates. After a socket has been opens the client sends a message +with the following format: +

command  host  service  color  time  +summary (\n) +
detailed status message line 1 (\n) +
detailed status message line 2 (\n) +
   ... +
detailed status message line n (\n)
+Where: +
command - The command being sent to the spong server indicating +a type of update message or a change in operating status of the client. +At present the only command defined is status which inidicates a +service status update message. +
host - The fully qualified domain name of the host the message +is for. +
service - The name of the service that the update message is +for. +
color - The status color of the service (green - ok, yellow +- warning, red - alert). +
time - The date/time of the update message in standard date +format (i.e. Thu Jan  1 00:00:00 UTC 1970) +
summary - The status summary message field. +
detailed status message - The remained lines of the message +which will be the detailed information of the status. Typically it can +be the output of the df command or the top processes by CPU utilization +or the detailed reponses of network checks. +
  +

+MODULES

+Both spong-client, spong-network and spong-message 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. +

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 +without any parameters. The client modules is expects to issue any systems +command and parse the output in order to determine the service status. +

Any threshold variables needed for warning and alert level trigger need +to be defined and placed into the /usr/local/etc/spong.conf +file. The threshold variable need to be uniquely named and should be named +according to the type of check being done (i.e. $DISKWARN or $DFWARN for +disk checks and $CPUWARN for CPU checks). +

Once the service status and messages have been determined the module +can call the &main::status() function in order to send the +information back to the spong-server. +

&status( SERVERADDR, HOST, SERVICE, COLOR, SUMMARY, MESSAGE )
+The arguments to the &status() function are: + +NETWORK MODULES +

Network modules defined checks that to be done on hosts over the network +to ensure that a network service is running. The modules are called with +the name of the host the check is to be done to. The modules is also expected +to put an alarm wrapper around the code that performs the check. This is +to prevent excessive delays dues to lost communications. It is suggested +that 10 seconds be used for the alarm setting. +

If an alert (red) status is generated, the module should retry the check +multiple times (3 is suggested). If the status is a warning (yellow), the +multiple retries of the check is optional. After the status condition has +been determined the check function should return three parameterers: +

+The network modules have two support functions,&main::check_tcp() +and &main::check_simple(),  which can simplify simple TCP +port checks. +

&main::check_tcp( host, port, data ) +

The arguments to &main::check_tcp() are: +

+The function &main::check_tcp() will make a connection to +the given PORT on the HOST and send a message (DATA). It then returns what +it gets back to the caller. +

&main::check_simple( host, port, +send, check, service) +

The arguments to &main::check_simple() are: +

+The function &main::check_simple() is a generic TCP port checking +routine. This will go out connect to a given port  (using &main::check_tcp())and +check to make sure you get back expected results. The function returned +three parameters: + +MESSAGE MODULES +

Message modules are function called to send a notification message to +a contact on a specific service or service. The messaging functions are +called with the contact's identification for the service that the function +sends messages to. The messaging function is expected to take care of all +of the data formatitng and communications logic to send a notification +message to the contact. +

The messaging functions has access to the global variable in order format +a notification message: +

+There are to support functions that be used to format a message and send +the message via e-mail: &main::email_status() and &main::email_mini_status().  +Both functions format e-mail message to be send to RECIPIENTS, but &email_mini_status() +sends out a shorter mail message which is more suitable for SMS and smaller +alpha pagers. +

Both functions are called thusly: +

&main::email_status( recipient, flags ) +
&main::email_mini_status( recipient, flags ) +

Where the arguments to the functions are: +

+The only flag current defined is 'shortsubject'. This prevents $color, +$hostname, and $summary from being placed on the subject: line. +
  +

+CREATING MODULES

+Creating the actual modules is very trivia to do. Create your module by +following the appropriate template from below. +
+
  • +spong-client module template
    • + +
  • +spong-network module template
    • + +
  • +spong-message module tempage
    • +
    +Then place your template module file into the appropirate directory below. + +Then test your modules by running the program with the --debug option to +if it is operating properly. + + -- 2.30.2