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:
-
SERVERADDR - Should be $SPONGSERVER
-
HOST - The full hostname of the machine
you are on
-
SERVICE - The a short name that describes the service
that you are reporting on.
-
COLOR - Either "red", "yellow", or "green"
-
SUMMARY - A short one line summary of the status
-
MESSAGE - More detailed information (can be multi-line)
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:
-
STATUS - The status color either "red", "yellow", or "green".
-
SUMMARY - A shoit line line summary of the status
-
MESSAGE - more detailed information (can be multi-lined)
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:
-
HOST - The name or ip address of the host to be checked.
-
PORT - The name of service to connect with.
-
DATA - The data to be send to the host after the port is opened.
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:
-
HOST - The name of ip address of the host to be checked.
-
PORT - The name of the port to connect with.
-
SEND - The messge to sent to the host after the port is opened.
-
CHECK - A perl regular express to be used to validate the response return
by the host.
-
SERVICE - The name of the sevive being check. It is used in the summary
and detailed status messages.
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:
-
STATUS - The status color either "red", "yellow", or "green".
-
SUMMARY - A shoit line line summary of the status
-
MESSAGE - more detailed information (can be multi-lined)
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:
-
$color - The status color of the message
-
$host - The fully qualified domain name of the host
-
$time - The date and time of the message being sent. (format is
epoch time or time())
-
$message - A one line summary status line
-
$duration - The current duration of the current status in seconds.
(a zero duration indicates a change in status)
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:
-
RECIPIENT - one or more e-mail recipients which placed in the to: line
of the mail message.
-
FLAGS - flags to alter the formating of the message.
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.
-
spong-client - LIBDIR/Spong/Client/plugins
-
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.