added files into CVS tree

diff --git a/pod/spong-client-mod-template.pod b/pod/spong-client-mod-template.pod
new file mode 100755 (executable)
index 0000000..7ff56b2
--- /dev/null
+++ b/pod/spong-client-mod-template.pod
@@ -0,0 +1,93 @@
+=head1 NAME\r
+\r
+spong-client-mod-template - how to create modules for spong-client\r
+\r
+=head1 DESCRIPTION\r
+\r
+This document describes how to create your own plugin modules for\r
+the B<spong-client> program. Your modules can be your own new custom check or\r
+they can replacements for the core Spong modules.\r
+\r
+This template assumes that you are creating a new client check\r
+called 'mailq'. The name of the file created should be 'check_mailq'. The\r
+file name for B<spong-client> modules should always be 'check_' plus the\r
+registry name (e.g. for the foo check, the registry name is 'foo' and the file\r
+name is 'check_foo').\r
+\r
+The line that has the assignment to I<$CHECKFUNC{'registry-name'}> is the\r
+key to the registry mechanism. It's what ties the registry name to the\r
+actual checking function.\r
+\r
+The registry name does not always have to match up to the service name as in\r
+this case of out module 'mailq'. If you where creating a new and improved\r
+function to check mail queues, you could create a module called 'my_mailq'. You\r
+would use the registry name 'my_mailq', but you would use the service name\r
+'mailq' in the C<E<amp>status()> function when reporting your info back to\r
+the server.\r
+\r
+check_mailq:\r
+\r
+  # Register my routine with plugin registry\r
+  $CHECKFUNCS{'mailq'} = &check_mailq;\r
+\r
+  # Sendmail mail queue check for mail servers. It checks the number of mail\r
+  # message queued against the $MAILQWARN AND $MAILQCRIT variables.\r
+  # It runs the command in the config variable $MAILQ to do it's check.\r
+\r
+  sub check_mailq {\r
+     my($mqcnt, $message, $color, $summary );\r
+\r
+     open (FOO,"$MAILQ |");\r
+\r
+     $mqcnt = 0;\r
+     while (&lt;FOO>) {\r
+        if (/Mail Queue\s+\((\d+)/) { $mqcnt = $1; }\r
+\r
+        # Grab enough to get the first 10 entries.\r
+        if (++$lines <= 35) { $message .= $_ };\r
+     }\r
+     close FOO;\r
+\r
+     $color = "green";\r
+\r
+     if ($mqcnt > $MAILQWARN) { $color = "yellow"; }\r
+     if ($mqcnt > $MAILQCRIT) { $color = "red"; }\r
+     $summary = "Mail Queue count = $mqcnt"\r
+\r
+     &main::debug("mailq - $color, $summary")\r
+     &main::status( $SPONGSERVER, $HOST, "mailq", $color,\r
+                    $summary, $message );\r
+\r
+  }\r
+\r
+  # I'm include perl code, I need this line.\r
+  1;\r
+\r
+Please note the final line. It is always required for a module file.\r
+\r
+The I<$MAILQWARN> and I<$MAILQCRIT> variables are added to the F<spong.conf>\r
+or F<spong.conf.E<lt>hostnameE<gt>> configuration files. These variable define\r
+the warning and alert threshold levels for your custom check.\r
+\r
+Configuration variable for your custom checks should be named to match them up\r
+with the name of your customized check. In our case, we started our variable\r
+names with MAILQ with matches up nicely with our module name of 'mailq'. Naming\r
+the threshold variables $WARN_SPOOL_LEVEL and $CRIT_SPOOL_LEVEL would have made it unclear as to which check they belonged to. Keep the names similar, it will\r
+make it easier on you and others to administer your setup in the future.\r
+\r
+=head1 SEE ALSO\r
+\r
+L<developer-guide>, L<spong-client>, L<spong.conf>\r
+\r
+=head1 AUTHOR\r
+\r
+Stephen L Johnson <F<sjohnson@monsters.org>>\r
+\r
+=head1 HISTORY\r
+\r
+Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong). Ed Hill\r
+original converted Big Brother (http://www.bb4.com) into Perl which diverged\r
+from Big Brother to become Spong. Ed Hill continued Spong development until\r
+version 2.1. Stephen L Johnson took over development in October, 1999 with his\r
+changes which became Spong 2.5.\r
+\r

diff --git a/pod/spong-network-mod-template.pod b/pod/spong-network-mod-template.pod
new file mode 100755 (executable)
index 0000000..e8a50a4
--- /dev/null
+++ b/pod/spong-network-mod-template.pod
@@ -0,0 +1,95 @@
+=head1 NAME\r
+\r
+spong-nework-mod-template - A sample spong-network check module\r
+\r
+=head1 DESCRIPTION\r
+\r
+This document describes a sample plugin module for the B<spong-network>\r
+program. Any modules that you create can be custom network checks, or they\r
+can be replacements for the core Spong modules.\r
+\r
+This template assumes that you are creating a network check called\r
+'dns'. The name of the file created should be 'check_dns'. The file name\r
+should always be 'check_' plus the registry name (e.g. for the foo check,\r
+the registry name is 'foo' and the file name is 'check_foo'.\r
+\r
+The line that has the assignment to $PLUGINS{'registry-name'} is the\r
+key to the registry mechanism. It's what ties the registry name to the\r
+the checking function.\r
+\r
+The registry name does not always have to match up to the service name as in\r
+the case of our module 'dns'. If you where creating a new and improved function\r
+to ping and traceroute, you could create a module called 'ping_trace'.  You\r
+would use the registry name 'ping_trace', but you would use the service name\r
+'ping' in the C<E<amp>main::status()> function when reporting your information\r
+back to the server.\r
+\r
+check_dns:\r
+\r
+  # Register the routine with the plugin registry\r
+  $PLUGINS{'dns'} = \&check_dns;\r
+\r
+  # Check to see if they have the Net::DNS module installed, and if they do we\r
+  # can then do DNS queries, and see if DNS servers are alive.\r
+\r
+  eval "require Net::DNS;";\r
+  if( ! $@ ) { $dns = 1; } else { $dns = 0; }\r
+\r
+  # This check will (if the Net::DNS module is available) connect to a DNS\r
+  # server and ask that server to resolve it's own name. If it can do that,\r
+  # then we assume it is ok - If it can't then something is wrong.\r
+\r
+  sub check_dns {\r
+      my( $host ) = @_;\r
+      my( $color, $summary, $message ) = ( "green", "", "" );\r
+\r
+      if( ! $dns ) {\r
+         $summary = "can't do DNS lookups, Net::DNS not installed";\r
+         &main::debug( "dns - $host - $color, $summary" );\r
+         return ( "yellow", $summary,\r
+         "In order to do DNS queries you must install the Net::DNS " .\r
+         "Perl module.\nYou can find the module at your nearest CPAN " .\r
+         "archive or http://www.perl.com/CPAN/\n" )\r
+      }\r
+\r
+      my $resolver = new Net::DNS::Resolver;</tt>\r
+      $resolver->nameservers( $host );\r
+      $resolver->retrans(2);\r
+      $resolver->retry(1);\r
+      $resolver->recurse(0);\r
+      my $q = $resolver->search( $host, "A" );</tt>\r
+\r
+      if( defined $q && defined $q->answer && defined (($q->answer)[0]) ) {\r
+          $color = "green";\r
+          $summary = "dns ok";\r
+      } else {\r
+         $color = "red";\r
+         $summary = "can't resolve $host";</tt>\r
+         $message = "can't resolve $host\n";\r
+      }\r
+\r
+      &main::debug( "dns - $host - $color, $summary" );\r
+      return( $color, $summary, $message );\r
+  }\r
+\r
+  # I'm included perl code, I need this line.</tt>\r
+  1;\r
+\r
+Please note the final line. It is always required for a module file.\r
+\r
+=head1 SEE ALSO\r
+\r
+L<developer-guide>, L<spong-network>, L<spong.conf>\r
+\r
+=head1 AUTHOR\r
+\r
+Stephen L Johnson <F<sjohnson@monsters.org>>\r
+\r
+=head1 HISTORY\r
+\r
+Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong). Ed Hill\r
+original converted Big Brother (http://www.bb4.com) into Perl which diverged\r
+from Big Brother to become Spong. Ed Hill continued Spong development until\r
+version 2.1. Stephen L Johnson took over development in October, 1999 with his\r
+changes which became Spong 2.5.\r
+\r

diff --git a/pod/spong.groups.pod b/pod/spong.groups.pod
new file mode 100755 (executable)
index 0000000..435d1fc
--- /dev/null
+++ b/pod/spong.groups.pod
@@ -0,0 +1,148 @@
+=head1 NAME
+
+B<spong.groups> - define groups of spong hosts
+
+
+=head1 DESCRIPTION
+
+The F<spong.hosts> file defines two things. 1) The hosts you want to monitor
+(and the attributes associated with each host), and 2) The humans that will 
+be contacted when a given host has problems (and the attributes associated
+with each human).
+
+The F<spong.groups> file defines a set of hosts from F<spong.hosts>. This
+file is used by the Spong display programs B<www-spong> and B<spong> for
+formating and filters output displays. The B<spong-message> uses this
+in it's messaging rules to do inclusion or exclusion of notifications for
+groups of hosts.
+
+Any number of groups can be added created. A host belong to multiple groups
+or no groups. There is a default group of ALL which all hosts in F<spong.conf>
+are automatically a member. 
+
+B<Note:> You do not have to add hosts into the 'ALL' group in the
+F<spong.groups> file. It is done automatically.
+
+=head2 %GROUPS
+
+Each host should have the following attributes associated with it:
+
+=over 
+
+=item * name
+
+The name of the group. This attribute is used extensively in Spong
+Display programs.
+
+=item * summary
+
+A description of the group
+
+=item * members
+
+This is a list of host names that are members of the groups. The hosts names
+should be those used in the F<spong.hosts> program
+
+=back
+
+Optionally, the follow attributes can also be assigned to a group:
+
+=over 
+
+=item * compress
+
+This attribute indiciates whether or not empty empty service columns should
+be removed when displaying this groups. Otherwise all of the services in
+the Spong database will be shown. This attribute should be 0 or 1. The default
+value is 0 (don't compress).
+
+=item display
+
+This attribute controls whether a group will be displayed on Host Groups
+displays of Spong Display programs. Set this value off f you intend to just use
+a group for notification matching B<spong-message>.
+
+This attribute should be 0 or 1. The default value is 1 (display the group).
+
+=back
+
+
+=HEAD1 FORMAT
+
+The F<spong.conf> file is simply Perl code that gets imported by each Spong
+program, so the only real format restrictions is just what is syntactically
+correct in Perl (which some would say is anything 8-).
+
+What is expected in this file is the definition for one hash of hashes (in
+Perl speak). The I<%GROUPS> hash,  If you are
+not comfortable with Perl lingo, then just think of them as stanza definitions.
+
+The following describes the <%GROUP> hash.
+
+  %GROUPS = ( [stanza], [stanza], [stanza] );
+
+where [stanza] is a second hash, that looks like the following:
+
+  'servers' => { name    => 'Main servers',
+                 summary => 'Main servers that are up 24x7',
+                 members => [ 'zero.monsters.org',
+                              'godzilla.monsters.org',
+                           ],
+                 compress = 0;
+                 display = 1;
+               }
+
+<p>I know the format can be a little odd at first, but I chose it because
+of both its simplicity to work with in the code (I don't have to parse
+anything - Perl does all the work), and because it is easy to extend -
+adding additional attributes is quite straightforward.
+
+=head1 EXAMPLES
+
+Here are some lines from my spong.groups file to show you possible
+configurations.
+
+
+  %GROUPS = (
+   'all' =>   { name    => 'All Systems',
+                summary => "This groups contains all hosts monitored by spong" },
+
+   'servers' => { name    => 'Main servers',
+                  summary => 'Main servers that are up 24x7',
+                  members => [ 'zero.monsters.org',
+                               'godzilla.monsters.org',
+                             ],
+                },
+
+   'windows' => { name => 'Windows Hosts',
+                  summary => 'Computers running Windows or NT',
+                  members => [ 'mothra.monsters.org',
+                            ],
+                  compress => 1,
+              },
+
+   'msgtest' => { name => 'spong-message groups',
+                  summary => 'A group to test spong-message rules matching',
+                  members => ['godzilla.monsters.org',
+                              'ghidora.monsters.org.',
+                             ],
+                  display => 0;  # Don't display this groups
+
+  );
+
+=head1 SEE ALSO
+
+the <i>spong-server</i> manpage , the <i>spong-network</i> manpage , the
+<i>spong-message</i> manpage
+<p>
+<hr>
+<h1>
+<a NAME="spong.hosts_author_0"></a>AUTHOR</h1>
+Ed Hill (<a href="MAILTO:ed-hill@uiowa.edu">ed-hill@uiowa.edu</a>), Unix
+System Administrator, The University of Iowa
+<br>Stephen L Johnson (<a href="MAILTO:stephen.johnson@mail.state.ar.us">stephen.johnson@mail.state.ar.us</a>)
+or (<a href="MAILTO:sjohnson@monsters.org">sjohnson@monsters.org</a>),
+Unix System Administator, DIS - State of Arkansas
+<p>Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong).
+</body>
+</html>