From: Stephen L Johnson 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 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 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 Cstatus()> 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 +or FhostnameE> 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, L, L + +=head1 AUTHOR + +Stephen L Johnson > + +=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 +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 Cmain::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; + $resolver->nameservers( $host ); + $resolver->retrans(2); + $resolver->retry(1); + $resolver->recurse(0); + my $q = $resolver->search( $host, "A" ); + + if( defined $q && defined $q->answer && defined (($q->answer)[0]) ) { + $color = "green"; + $summary = "dns ok"; + } else { + $color = "red"; + $summary = "can't resolve $host"; + $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. + 1; + +Please note the final line. It is always required for a module file. + +=head1 SEE ALSO + +L, L, L + +=head1 AUTHOR + +Stephen L Johnson > + +=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 - define groups of spong hosts + + +=head1 DESCRIPTION + +The F 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 file defines a set of hosts from F. This +file is used by the Spong display programs B and B for +formating and filters output displays. The B 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 +are automatically a member. + +B You do not have to add hosts into the 'ALL' group in the +F 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 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. + +This attribute should be 0 or 1. The default value is 1 (display the group). + +=back + + +=HEAD1 FORMAT + +The F 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; + } + +

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 spong-server manpage , the spong-network manpage , the +spong-message manpage +

+

+

+AUTHOR

+Ed Hill (ed-hill@uiowa.edu), Unix +System Administrator, The University of Iowa +
Stephen L Johnson (stephen.johnson@mail.state.ar.us) +or (sjohnson@monsters.org), +Unix System Administator, DIS - State of Arkansas +

Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong). + +