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

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 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
  • spong-server data module template
  • 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.