--- /dev/null
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">\r
+<html>\r
+<head>\r
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">\r
+ <meta name="Author" content="noman">\r
+ <meta name="GENERATOR" content="Mozilla/4.6 [en] (WinNT; I) [Netscape]">\r
+ <title>developer-guide</title>\r
+</head>\r
+<body>\r
+\r
+<h1>\r
+<a NAME="name"></a>NAME</h1>\r
+<b>developer-guide</b> - developer's guild to Spong\r
+<br>\r
+<hr WIDTH="100%">\r
+<h1>\r
+<a NAME="description"></a>DESCRIPTION</h1>\r
+This is the developer guild to Spong. The man page documents the inner\r
+works of the client and server programs. It also describes the plugins\r
+mechanism of the <i><a href="spong-client.html">spong-client</a></i> and\r
+<i><a href="spong-network.html">spong-network</a>, </i>so that new check\r
+modules can be developed for this programs.\r
+<br> \r
+<h1>\r
+<a NAME="protocols"></a>PROTOCOLS</h1>\r
+This section deals with the low level communucation protocols that the\r
+clients use to talk with the <i><a href="spong-server.html">spong-server</a></i>.\r
+The spong and Big Brothers protocols almost identical. they vary only in\r
+the data format.\r
+<p><a NAME="spong-protocol"></a><b>SPONG PROTOCOL</b>\r
+<br>The <i>spong-server</i> listens in on port 1998 for status updates\r
+from clients. After a socket has been opens the client sends a message\r
+with the following format:\r
+<blockquote><tt>command host service color time \r
+summary (\n)</tt>\r
+<br><tt>detailed status message line 1 (\n)</tt>\r
+<br><tt>detailed status message line 2 (\n)</tt>\r
+<br><tt> ...</tt>\r
+<br><tt>detailed status message line n (\n)</tt></blockquote>\r
+Where:\r
+<br><i>command</i> - The command being sent to the spong server indicating\r
+a type of update message or a change in operating status of the client.\r
+At present the only command defined is <i>status</i> which inidicates a\r
+service status update message.\r
+<br><i>host</i> - The fully qualified domain name of the host the message\r
+is for.\r
+<br><i>service</i> - The name of the service that the update message is\r
+for.\r
+<br><i>color</i> - The status color of the service (green - ok, yellow\r
+- warning, red - alert).\r
+<br><i>time</i> - The date/time of the update message in epoch time format\r
+(i.e. the number of seconds since 01/01/70, 00:00 AM)\r
+<br><i>summary</i> - The status summary message field.\r
+<br><i>detailed status message</i> - The remained lines of the message\r
+which will be the detailed information of the status. Typically it can\r
+be the output of the df command or the top processes by CPU utilization\r
+or the detailed reponses of network checks.\r
+<br> \r
+<p><a NAME="bb-protocol"></a><b>BIG BROTHER PROTOCOL</b>\r
+<br>The <i>spong-server</i> listens in on port 1984 for status Big Brother\r
+client updates. After a socket has been opens the client sends a message\r
+with the following format:\r
+<blockquote><tt>command host service color time \r
+summary (\n)</tt>\r
+<br><tt>detailed status message line 1 (\n)</tt>\r
+<br><tt>detailed status message line 2 (\n)</tt>\r
+<br><tt> ...</tt>\r
+<br><tt>detailed status message line n (\n)</tt></blockquote>\r
+Where:\r
+<br><i>command</i> - The command being sent to the spong server indicating\r
+a type of update message or a change in operating status of the client.\r
+At present the only command defined is <i>status</i> which inidicates a\r
+service status update message.\r
+<br><i>host</i> - The fully qualified domain name of the host the message\r
+is for.\r
+<br><i>service</i> - The name of the service that the update message is\r
+for.\r
+<br><i>color</i> - The status color of the service (green - ok, yellow\r
+- warning, red - alert).\r
+<br><i>time</i> - The date/time of the update message in standard date\r
+format (i.e. Thu Jan 1 00:00:00 UTC 1970)\r
+<br><i>summary</i> - The status summary message field.\r
+<br><i>detailed status message</i> - The remained lines of the message\r
+which will be the detailed information of the status. Typically it can\r
+be the output of the df command or the top processes by CPU utilization\r
+or the detailed reponses of network checks.\r
+<br> \r
+<h1>\r
+MODULES</h1>\r
+Both spong-client, spong-network and spong-message use routines which are\r
+modules. When the programs are initializating, they determine which modules\r
+are going to be required. The programs then go out and load each of the\r
+modules from the library directory. When the modules are loaded they register\r
+themself with the plugins registery. The plugin registry is the mechanism\r
+that the client programs keep track of the modules into order to run them.\r
+<p><a NAME="client-modules"></a><b>CLIENT MODULES</b>\r
+<p>Client modules define checks which are to be done on the host that the\r
+spong-client program is running on. The module's check function is called\r
+without any parameters. The client modules is expects to issue any systems\r
+command and parse the output in order to determine the service status.\r
+<p>Any threshold variables needed for warning and alert level trigger need\r
+to be defined and placed into the <a href="spong.conf.html">/usr/local/etc/spong.conf</a>\r
+file. The threshold variable need to be uniquely named and should be named\r
+according to the type of check being done (i.e. $DISKWARN or $DFWARN for\r
+disk checks and $CPUWARN for CPU checks).\r
+<p>Once the service status and messages have been determined the module\r
+can call the <tt>&main::status()</tt> function in order to send the\r
+information back to the spong-server.\r
+<pre><a NAME="status"></a>&status( SERVERADDR, HOST, SERVICE, COLOR, SUMMARY, MESSAGE )</pre>\r
+The arguments to the <tt>&<i>status()</i></tt> function are:\r
+<ul>\r
+<li>\r
+SERVERADDR - Should be $SPONGSERVER</li>\r
+\r
+<li>\r
+HOST - The full hostname of the machine\r
+you are on</li>\r
+\r
+<li>\r
+SERVICE - The a short name that describes the service\r
+that you are reporting on.</li>\r
+\r
+<li>\r
+COLOR - Either "red", "yellow", or "green"</li>\r
+\r
+<li>\r
+SUMMARY - A short one line summary of the status</li>\r
+\r
+<li>\r
+MESSAGE - More detailed information (can be multi-line)</li>\r
+</ul>\r
+<a NAME="network-modules"></a><b>NETWORK MODULES</b>\r
+<p>Network modules defined checks that to be done on hosts over the network\r
+to ensure that a network service is running. The modules are called with\r
+the name of the host the check is to be done to. The modules is also expected\r
+to put an alarm wrapper around the code that performs the check. This is\r
+to prevent excessive delays dues to lost communications. It is suggested\r
+that 10 seconds be used for the alarm setting.\r
+<p>If an alert (red) status is generated, the module should retry the check\r
+multiple times (3 is suggested). If the status is a warning (yellow), the\r
+multiple retries of the check is optional. After the status condition has\r
+been determined the check function should return three parameterers:\r
+<ul>\r
+<li>\r
+STATUS - The status color either "red", "yellow", or "green".</li>\r
+\r
+<li>\r
+SUMMARY - A shoit line line summary of the status</li>\r
+\r
+<li>\r
+MESSAGE - more detailed information (can be multi-lined)</li>\r
+</ul>\r
+The network modules have two support functions,<i>&main::check_tcp()</i>\r
+and <i>&main::check_simple(), </i> which can simplify simple TCP\r
+port checks.\r
+<p><a NAME="check_tcp"></a><tt>&main::check_tcp( host, port, data )</tt>\r
+<p>The arguments to <tt>&main::check_tcp()</tt> are:\r
+<ul>\r
+<li>\r
+HOST - The name or ip address of the host to be checked.</li>\r
+\r
+<li>\r
+PORT - The name of service to connect with.</li>\r
+\r
+<li>\r
+DATA - The data to be send to the host after the port is opened.</li>\r
+</ul>\r
+The function <tt>&main::check_tcp()</tt> will make a connection to\r
+the given PORT on the HOST and send a message (DATA). It then returns what\r
+it gets back to the caller.\r
+<p><a NAME="check_simple"></a><tt>&main::check_simple( host, port,\r
+send, check, service)</tt>\r
+<p>The arguments to &main::check_simple() are:\r
+<ul>\r
+<li>\r
+HOST - The name of ip address of the host to be checked.</li>\r
+\r
+<li>\r
+PORT - The name of the port to connect with.</li>\r
+\r
+<li>\r
+SEND - The messge to sent to the host after the port is opened.</li>\r
+\r
+<li>\r
+CHECK - A perl regular express to be used to validate the response return\r
+by the host.</li>\r
+\r
+<li>\r
+SERVICE - The name of the sevive being check. It is used in the summary\r
+and detailed status messages.</li>\r
+</ul>\r
+The function <tt>&main::check_simple()</tt> is a generic TCP port checking\r
+routine. This will go out connect to a given port (using <tt>&main::check_tcp()</tt>)and\r
+check to make sure you get back expected results. The function returned\r
+three parameters:\r
+<ul>\r
+<li>\r
+STATUS - The status color either "red", "yellow", or "green".</li>\r
+\r
+<li>\r
+SUMMARY - A shoit line line summary of the status</li>\r
+\r
+<li>\r
+MESSAGE - more detailed information (can be multi-lined)</li>\r
+</ul>\r
+<a NAME="message-modules"></a><b>MESSAGE MODULES</b>\r
+<p>Message modules are function called to send a notification message to\r
+a contact on a specific service or service. The messaging functions are\r
+called with the contact's identification for the service that the function\r
+sends messages to. The messaging function is expected to take care of all\r
+of the data formatitng and communications logic to send a notification\r
+message to the contact.\r
+<p>The messaging functions has access to the global variable in order format\r
+a notification message:\r
+<ul>\r
+<li>\r
+<b>$color</b> - The status color of the message</li>\r
+\r
+<li>\r
+<b>$host</b> - The fully qualified domain name of the host</li>\r
+\r
+<li>\r
+<b>$time</b> - The date and time of the message being sent. (format is\r
+epoch time or time())</li>\r
+\r
+<li>\r
+<b>$message</b> - A one line summary status line</li>\r
+\r
+<li>\r
+<b>$duration</b> - The current duration of the current status in seconds.\r
+(a zero duration indicates a change in status)</li>\r
+</ul>\r
+There are to support functions that be used to format a message and send\r
+the message via e-mail: <tt>&main::email_status()</tt> and <tt>&main::email_mini_status()</tt>. \r
+Both functions format e-mail message to be send to RECIPIENTS, but <tt>&email_mini_status()</tt>\r
+sends out a shorter mail message which is more suitable for SMS and smaller\r
+alpha pagers.\r
+<p>Both functions are called thusly:\r
+<p><tt>&main::email_status( recipient, flags )</tt>\r
+<br><tt>&main::email_mini_status( recipient, flags )</tt>\r
+<p>Where the arguments to the functions are:\r
+<ul>\r
+<li>\r
+RECIPIENT - one or more e-mail recipients which placed in the to: line\r
+of the mail message.</li>\r
+\r
+<li>\r
+FLAGS - flags to alter the formating of the message.</li>\r
+</ul>\r
+The only flag current defined is 'shortsubject'. This prevents $color,\r
+$hostname, and $summary from being placed on the subject: line.\r
+<br> \r
+<h1>\r
+<a NAME="developer-guide.creating_modules"></a>CREATING MODULES</h1>\r
+Creating the actual modules is very trivia to do. Create your module by\r
+following the appropriate template from below.\r
+<blockquote>\r
+<li>\r
+<a href="spong-client-mod-template.html">spong-client module template</a></li>\r
+\r
+<li>\r
+<a href="spong-network-mod-template.html">spong-network module template</a></li>\r
+\r
+<li>\r
+<a href="spong-message-mod-template.html">spong-message module tempage</a></li>\r
+</blockquote>\r
+Then place your template module file into the appropirate directory below.\r
+<ul>\r
+<li>\r
+spong-client - LIBDIR/Spong/Client/plugins</li>\r
+\r
+<li>\r
+spong-nework - LIBDIR/Spong/Network/plugins</li>\r
+\r
+<li>\r
+spong-message - LIBDIR/Spong/Message/plugins</li>\r
+</ul>\r
+Then test your modules by running the program with the --debug option to\r
+if it is operating properly.\r
+</body>\r
+</html>\r
projects / spong.git / commitdiff