From: Stephen L Johnson <sjohnson@monsters.org>
Date: Fri, 14 Jul 2000 04:41:22 +0000 (+0000)
Subject: added files into CVS tree
X-Git-Tag: spong-2_7-alpha8~7
X-Git-Url: http://git.etc.gen.nz/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a2fe902dcef5b823b065133c40dc1f9622a41043;p=spong.git
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
index 0000000..7ff56b2
--- /dev/null
+++ b/pod/spong-client-mod-template.pod
@@ -0,0 +1,93 @@
+=head1 NAME
+
+spong-client-mod-template - how to create modules for spong-client
+
+=head1 DESCRIPTION
+
+This document describes how to create your own plugin modules for
+the B<spong-client> program. Your modules can be your own new custom check or
+they can replacements for the core Spong modules.
+
+This template assumes that you are creating a new client check
+called 'mailq'. The name of the file created should be 'check_mailq'. The
+file name for B<spong-client> modules should always be 'check_' plus the
+registry name (e.g. for the foo check, the registry name is 'foo' and the file
+name is 'check_foo').
+
+The line that has the assignment to I<$CHECKFUNC{'registry-name'}> is the
+key to the registry mechanism. It's what ties the registry name to the
+actual checking function.
+
+The registry name does not always have to match up to the service name as in
+this case of out module 'mailq'. If you where creating a new and improved
+function to check mail queues, you could create a module called 'my_mailq'. You
+would use the registry name 'my_mailq', but you would use the service name
+'mailq' in the C<E<amp>status()> function when reporting your info back to
+the server.
+
+check_mailq:
+
+ # Register my routine with plugin registry
+ $CHECKFUNCS{'mailq'} = &check_mailq;
+
+ # Sendmail mail queue check for mail servers. It checks the number of mail
+ # message queued against the $MAILQWARN AND $MAILQCRIT variables.
+ # It runs the command in the config variable $MAILQ to do it's check.
+
+ sub check_mailq {
+ my($mqcnt, $message, $color, $summary );
+
+ open (FOO,"$MAILQ |");
+
+ $mqcnt = 0;
+ while (<FOO>) {
+ if (/Mail Queue\s+\((\d+)/) { $mqcnt = $1; }
+
+ # Grab enough to get the first 10 entries.
+ if (++$lines <= 35) { $message .= $_ };
+ }
+ close FOO;
+
+ $color = "green";
+
+ if ($mqcnt > $MAILQWARN) { $color = "yellow"; }
+ if ($mqcnt > $MAILQCRIT) { $color = "red"; }
+ $summary = "Mail Queue count = $mqcnt"
+
+ &main::debug("mailq - $color, $summary")
+ &main::status( $SPONGSERVER, $HOST, "mailq", $color,
+ $summary, $message );
+
+ }
+
+ # I'm include perl code, I need this line.
+ 1;
+
+Please note the final line. It is always required for a module file.
+
+The I<$MAILQWARN> and I<$MAILQCRIT> variables are added to the F<spong.conf>
+or F<spong.conf.E<lt>hostnameE<gt>> configuration files. These variable define
+the warning and alert threshold levels for your custom check.
+
+Configuration variable for your custom checks should be named to match them up
+with the name of your customized check. In our case, we started our variable
+names with MAILQ with matches up nicely with our module name of 'mailq'. Naming
+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
+make it easier on you and others to administer your setup in the future.
+
+=head1 SEE ALSO
+
+L<developer-guide>, L<spong-client>, L<spong.conf>
+
+=head1 AUTHOR
+
+Stephen L Johnson <F<sjohnson@monsters.org>>
+
+=head1 HISTORY
+
+Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong). Ed Hill
+original converted Big Brother (http://www.bb4.com) into Perl which diverged
+from Big Brother to become Spong. Ed Hill continued Spong development until
+version 2.1. Stephen L Johnson took over development in October, 1999 with his
+changes which became Spong 2.5.
+
diff --git a/pod/spong-network-mod-template.pod b/pod/spong-network-mod-template.pod
new file mode 100755
index 0000000..e8a50a4
--- /dev/null
+++ b/pod/spong-network-mod-template.pod
@@ -0,0 +1,95 @@
+=head1 NAME
+
+spong-nework-mod-template - A sample spong-network check module
+
+=head1 DESCRIPTION
+
+This document describes a sample plugin module for the B<spong-network>
+program. Any modules that you create can be custom network checks, or they
+can be replacements for the core Spong modules.
+
+This template assumes that you are creating a network check called
+'dns'. The name of the file created should be 'check_dns'. The file name
+should always be 'check_' plus the registry name (e.g. for the foo check,
+the registry name is 'foo' and the file name is 'check_foo'.
+
+The line that has the assignment to $PLUGINS{'registry-name'} is the
+key to the registry mechanism. It's what ties the registry name to the
+the checking function.
+
+The registry name does not always have to match up to the service name as in
+the case of our module 'dns'. If you where creating a new and improved function
+to ping and traceroute, you could create a module called 'ping_trace'. You
+would use the registry name 'ping_trace', but you would use the service name
+'ping' in the C<E<amp>main::status()> function when reporting your information
+back to the server.
+
+check_dns:
+
+ # Register the routine with the plugin registry
+ $PLUGINS{'dns'} = \&check_dns;
+
+ # Check to see if they have the Net::DNS module installed, and if they do we
+ # can then do DNS queries, and see if DNS servers are alive.
+
+ eval "require Net::DNS;";
+ if( ! $@ ) { $dns = 1; } else { $dns = 0; }
+
+ # This check will (if the Net::DNS module is available) connect to a DNS
+ # server and ask that server to resolve it's own name. If it can do that,
+ # then we assume it is ok - If it can't then something is wrong.
+
+ sub check_dns {
+ my( $host ) = @_;
+ my( $color, $summary, $message ) = ( "green", "", "" );
+
+ if( ! $dns ) {
+ $summary = "can't do DNS lookups, Net::DNS not installed";
+ &main::debug( "dns - $host - $color, $summary" );
+ return ( "yellow", $summary,
+ "In order to do DNS queries you must install the Net::DNS " .
+ "Perl module.\nYou can find the module at your nearest CPAN " .
+ "archive or http://www.perl.com/CPAN/\n" )
+ }
+
+ my $resolver = new Net::DNS::Resolver;</tt>
+ $resolver->nameservers( $host );
+ $resolver->retrans(2);
+ $resolver->retry(1);
+ $resolver->recurse(0);
+ my $q = $resolver->search( $host, "A" );</tt>
+
+ if( defined $q && defined $q->answer && defined (($q->answer)[0]) ) {
+ $color = "green";
+ $summary = "dns ok";
+ } else {
+ $color = "red";
+ $summary = "can't resolve $host";</tt>
+ $message = "can't resolve $host\n";
+ }
+
+ &main::debug( "dns - $host - $color, $summary" );
+ return( $color, $summary, $message );
+ }
+
+ # I'm included perl code, I need this line.</tt>
+ 1;
+
+Please note the final line. It is always required for a module file.
+
+=head1 SEE ALSO
+
+L<developer-guide>, L<spong-network>, L<spong.conf>
+
+=head1 AUTHOR
+
+Stephen L Johnson <F<sjohnson@monsters.org>>
+
+=head1 HISTORY
+
+Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong). Ed Hill
+original converted Big Brother (http://www.bb4.com) into Perl which diverged
+from Big Brother to become Spong. Ed Hill continued Spong development until
+version 2.1. Stephen L Johnson took over development in October, 1999 with his
+changes which became Spong 2.5.
+
diff --git a/pod/spong.groups.pod b/pod/spong.groups.pod
new file mode 100755
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>