From: Stephen L Johnson <sjohnson@monsters.org>
Date: Wed, 10 May 2000 04:13:00 +0000 (+0000)
Subject: added inline pod documentation
X-Git-Tag: spong-2_7-alpha7~28
X-Git-Url: http://git.etc.gen.nz/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d2fa61e0d9bafc1bd9450edd581c7000b0aa656b;p=spong.git

added inline pod documentation
---

diff --git a/src/lib/Spong/Network/plugins/check_interfaces b/src/lib/Spong/Network/plugins/check_interfaces
index da01cc0..f2b689e 100644
--- a/src/lib/Spong/Network/plugins/check_interfaces
+++ b/src/lib/Spong/Network/plugins/check_interfaces
@@ -1,3 +1,16 @@
+=head1 NAME
+
+B<check_interfaces> - spong-network module to check for down intefaces via SNMP
+
+=head1 DESCRIPTION
+
+This is a plugin module for the Spong L<spong-network> program. It is a core
+Spong module. The B<check_interfaces> module checks for down network interfaces
+on a host by polling via SNMP. It reports any interfaces that are
+administratively up but operationally not up.
+
+=cut
+
 # Register the routine with the plugin registry
 $PLUGINS{'interfaces'} = \&check_interfaces;
 
@@ -97,3 +110,90 @@ sub check_interfaces {
 	debug ("interfaces - $host - $color, $summary", 4 );
 	return ($color, $summary, $message );
 }
+
+1;
+
+
+__END__
+
+=head2 Output Returned
+
+=over 4
+
+=item Status
+
+If all interfaces are operationally up, a 'green' status is returned. If a host
+is found to have no interfaces a 'yellow' status is returned. Any interfaces
+that are operationally down and administratively up, a 'red' status is
+returned. Any SNMP session problems will also result in a 'red' status being
+returned.
+
+=item Summary Field
+
+In normal operation, the status field will show "all interfaces up". If one or
+more network interfaces are down, it will show "some interfaces are down".
+Otherwise the summary field will have a description of what the problem or
+anamoly is.
+
+=item Detail Message Field
+
+In normal opereration the detail message field will have a list of all of the
+network interfaces in the I<MIBII ifTable> table along with the interface
+description (I<ifDesc>), type (I<ifType>), administrative status
+(I<ifAdminStatus>) and operational status (I<ifOperStatus>). Otherwise this
+field will have a detailed description of the cause of an error.
+
+=back
+
+=head2 Configuration
+
+=over 4
+
+=item SNMP Community Name
+
+The default SNMP Community name is I<public>. To override the default name
+specify a C<snmp_ community> attribute in a host's entry in the I<%HOSTS> variabile
+of the L<spong.conf> configuration file. See the L<Examples|"EXAMPLES") section
+for a detailed example.
+
+=back
+
+=head1 EXAMPLES
+
+ %HOSTS = ( 'hostname.my-inc.com' => { 'services'  => 'interfaces',
+                                       'ip_addr'   => ['192.168.13.123'],
+                                       'community' => 'local-read',
+                                       },
+            );
+
+
+=head1 SEE ALSO
+
+L<spong-network>, L<check_snmp>,
+L<spong-network Modules Template|spong-network-mod-template>,
+L<Spong Developer Guide|develop-guide>
+
+=head1 NOTES
+
+The B<check_interfaces> module use SNMP to poll a host. It retrieves the
+B<ifIndex>, B<ifDesc>, B<ifType>, B<ifAdminStatus>, and  B<ifOperStatus> fields
+for every entry in the B<ifTable> table. The module then scans all of all of
+the network interfaces inretrieved from the table. Any interface that is
+administratively up and is not operationally up will result in an critical
+status (red) being return.
+
+=head1 RESTRICTIONS
+
+B<check_interfaces> uses the C<SNMP_Session>, C<SNMP_utils> and C<BER> modules
+from the B<SNMP_Session> package. The B<SNMP_Session> package must be installed
+in order for this module to work.
+
+The latest version of B<SNMP_Session> package can be obtained from:
+
+  http://www.switch.ch/misc/leinen/snmp/perl/index.html 
+
+=head1 AUTHOR
+
+The original author is Mike Bayliss <F<mbayliss@datax.be>>. Extra debug code
+and enhancements added by Stephen L Johnson <F<sjohnson@monsters.org>>.
+
diff --git a/src/lib/Spong/Network/plugins/check_snmp b/src/lib/Spong/Network/plugins/check_snmp
index 52f86a3..78c4b23 100644
--- a/src/lib/Spong/Network/plugins/check_snmp
+++ b/src/lib/Spong/Network/plugins/check_snmp
@@ -1,3 +1,22 @@
+=head1 NAME
+
+B<check_snmp> - spong-network module to check for proper SNMP agent operation
+
+=head1 DESCRIPTION
+
+This is a plugin module for the Spong L<spong-network> program. It is a core
+Spong module. The B<check_snmp> module checks for the SNMP agent running
+in the host for proper operation. 
+
+The module check SNMP by issuing an I<snmpget> operation for the I<systemGroup>
+table of the host. If the operation is sucessfully, snmp service is deemed
+OK. The module also has an option check for the I<sysObjectId>. An expected
+I<sysObjectId> value can be specified to be checked against the I<sysObjectId>
+value retrieved in the snmpget operation. If the values don't agree, a
+critical (red) status is reported
+
+=cut
+
 # Register the routine with the plugin registry
 $PLUGINS{'snmp'} = \&check_snmp;
 
@@ -76,3 +95,97 @@ sub check_snmp {
 
 1;
 
+
+__END__
+
+=head2 Output Returned
+
+=over 4
+
+=item Status
+
+If the I<snmpget> operation is successfully, 'green' status is return. If an
+SNMP error occurs a 'red' status is returned.
+
+If an B<expect_objid> is specified for the host, a 'green' status is returned
+if the I<snmpget> operation is successful and the I<sysObjectId> value matches
+the B<expect_objid>. If the values don't match, a 'red' status is returned.
+
+=item Summary Field
+
+If there are no problems, "snmp ok" is returned. Otherwise the summary field
+will have a short description of that the problem or anamoly is.
+
+=item Detail Message Field
+
+If normal operation the detail message will have the values of the system
+description (I<sysDesc>), uptime (I<sysUpTime>), contact (I<sysContact>), name
+(I<sysName>), location (I<sysLocation>), and object id (I<sysObjectID>) fields
+from the System Group. If an B<expect_objid) was specified for the host and the
+retrived object id doesn't match, the expected value will also be listed.
+Otherwise this field will have a detailed description of the cause of an error.
+
+=back
+
+=head2 Configuration
+
+=over 4
+
+=item SNMP Community Name
+
+The default SNMP Community name is I<public>. To override the default name
+specify a C<snmp_community> attribute in a host's entry in the I<%HOSTS)
+variable in the L<spong.conf> configuration file. See the L<Examples|"EXAMPLES"
+section for a detailed example.
+
+=item Expected System Object ID
+
+You can specify an expected I<sysObjectID> value to be checked against the
+retrieved. Specify a C<expect_objid> attribute in a host's entry in the
+I<%HOSTS> variable in the L<spong.conf> configuration file. See the
+L<Examples|"EXAMPLES"> section for a detailed example.
+
+=back
+
+=head1 EXAMPLES
+
+ %HOSTS = ( 'hostname.my-inc.com' => { 'services'  => 'snmp',
+                                       'ip_addr'  => ['192.168.13.123'],
+                                       'snmp_community' => 'local-read',
+                                       'expect_objid' =>
+                                           '1.3.6.1.4.1.2021.250.10',
+          );
+
+=head1 SEE ALSO
+
+L<spong-network>, L<check_interfaces>,
+L<spong-network Modules Template|spong-network-mod-template>,
+L<Spong Developer's Guide|developer-guide>
+
+=head1 NOTES
+
+The B<check_snmp> module uses an SNMP I<snmpget> operation to poll a host.
+It retrieves the values of the system description (I<sysDesc>), uptime
+(I<sysUpTime>), contact (I<sysContact>), name (I<sysName>), location
+(I<sysLocation>), and object id (I<sysObjectID>) fields from the System Group.
+If the I<snmpget> operation was successful, the snmp service is deemed OK.
+
+If an optional B<expect_objid> value is specified for the host, it will be
+compared to the I<sysObjectID> value retrieved from the host. If the values
+don't match a critical ('red') status is generated.
+
+=head1 RESTRICTIONS
+
+B<check_interfaces> uses the C<SNMP_Session>, C<SNMP_utils> and C<BER> modules
+from the B<SNMP_Session> package. The B<SNMP_Session> package must be installed
+in order for this module to work.
+
+The latest version of B<SNMP_Session> package can be obtained from:
+
+  http://www.switch.ch/misc/leinen/snmp/perl/index.html 
+
+=head1 AUTHOR
+
+The original author is Mike Bayliss <F<mbayliss@datax.be>>. Extra debug code
+and enhancements added by Stephen L Johnson <F<sjohnson@monsters.org>>.
+