X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd-snmp.pod;h=1415cb17d4ca0dbeebff8ac991e62538d66b7281;hb=b17fa8a7c71eb9fbc67702d8f1cf8a53fb2fe8a7;hp=65a9b7c3d320098e40a3b491865e0067d8d53197;hpb=218c57128f2e54960133cff3e774b5ef9944068a;p=collectd.git

diff --git a/src/collectd-snmp.pod b/src/collectd-snmp.pod
index 65a9b7c3..1415cb17 100644
--- a/src/collectd-snmp.pod
+++ b/src/collectd-snmp.pod
@@ -10,23 +10,22 @@ collectd-snmp - Documentation of collectd's C<snmp plugin>
   # ...
   <Plugin snmp>
     <Data "powerplus_voltge_input">
-      Type "voltage"
       Table false
-      Instance "input_line1"
+      Type "voltage"
+      TypeInstance "input_line1"
       Scale 0.1
       Values "SNMPv2-SMI::enterprises.6050.5.4.1.1.2.1"
     </Data>
     <Data "hr_users">
-      Type "users"
       Table false
-      Instance ""
+      Type "users"
       Shift -1
       Values "HOST-RESOURCES-MIB::hrSystemNumUsers.0"
     </Data>
     <Data "std_traffic">
-      Type "if_octets"
       Table true
-      Instance "IF-MIB::ifDescr"
+      Type "if_octets"
+      TypeInstanceOID "IF-MIB::ifDescr"
       Values "IF-MIB::ifInOctets" "IF-MIB::ifOutOctets"
     </Data>
 
@@ -36,6 +35,8 @@ collectd-snmp - Documentation of collectd's C<snmp plugin>
       Community "community_string"
       Collect "std_traffic"
       Interval 120
+      Timeout 10
+      Retries 1
     </Host>
     <Host "some.server.mydomain.org">
       Address "192.168.0.42"
@@ -44,7 +45,7 @@ collectd-snmp - Documentation of collectd's C<snmp plugin>
       Collect "std_traffic" "hr_users"
     </Host>
     <Host "secure.router.mydomain.org">
-      Address "192.168.0.7"
+      Address "192.168.0.7:165"
       Version 3
       SecurityLevel "authPriv"
       Username "cosmo"
@@ -55,11 +56,13 @@ collectd-snmp - Documentation of collectd's C<snmp plugin>
       Collect "std_traffic"
     </Host>
     <Host "some.ups.mydomain.org">
-      Address "192.168.0.3"
+      Address "tcp:192.168.0.3"
       Version 1
       Community "more_communities"
       Collect "powerplus_voltge_input"
       Interval 300
+      Timeout 5
+      Retries 5
     </Host>
   </Plugin>
 
@@ -78,7 +81,7 @@ and ten threads are used.
 =head1 CONFIGURATION
 
 Since the aim of the C<snmp plugin> is to provide a generic interface to SNMP,
-it's configuration is not trivial and may take some time.
+its configuration is not trivial and may take some time.
 
 Since the C<Net-SNMP> library is used you can use all the environment variables
 that are interpreted by that package. See L<snmpcmd(1)> for more details.
@@ -134,25 +137,67 @@ C<IF-MIB::ifHCInOctets> and C<IF-MIB::ifHCOutOctets>. But, this is because of
 the B<Type> setting, not the B<Table> setting.
 
 Since the semantic of B<Instance> and B<Values> depends on this setting you
-need to set it before setting them. Doing vice verse will result in undefined
+need to set it before setting them. Doing vice versa will result in undefined
 behavior.
 
+=item B<Plugin> I<Plugin>
+
+Use I<Plugin> as the plugin name of the values that are dispatched.
+Defaults to C<snmp>.
+
+=item B<PluginInstance> I<Instance>
+
+Sets the plugin-instance of the values that are dispatched to I<Instance> value.
+
+When B<Table> is set to I<true> and B<PluginInstanceOID> is set then this option
+has no effect.
+
+Defaults to an empty string.
+
+=item B<TypeInstance> I<Instance>
+
+Sets the type-instance of the values that are dispatched to I<Instance> value.
+
+When B<Table> is set to I<true> and B<TypeInstanceOID> is set then this option
+has no effect.
+
+Defaults to an empty string.
+
+=item B<TypeInstanceOID> I<OID>
+
+=item B<PluginInstanceOID> I<OID>
+
+If B<Table> is set to I<true>, I<OID> is interpreted as an SNMP-prefix that will
+return a list of values. Those values are then used as the actual type-instance
+or plugin-instance of dispatched metrics. An example would be the
+C<IF-MIB::ifDescr> subtree. L<variables(5)> from the SNMP distribution describes
+the format of OIDs. When set to empty string, then "SUBID" will be used as the
+instance.
+
+Prefix may be set for values with use of B<InstancePrefix> option.
+
+When B<Table> is set to I<false> these options has no effect.
+Only one of these options may be used in the same B<Data> block.
+
+Defaults:
+
+B<TypeInstanceOID> defaults to an empty string.
+
+B<PluginInstanceOID> is not configured.
+
 =item B<Instance> I<Instance>
 
-Sets the type-instance of the values that are dispatched. The meaning of this
-setting depends on whether B<Table> is set to I<true> or I<false>:
+Attention: this option exists for backwards compatibility only and will be
+removed in next major release. Please use B<TypeInstance> / B<TypeInstanceOID>
+instead.
 
-If B<Table> is set to I<true>, I<Instance> is interpreted as an SNMP-prefix
-that will return a list of values. Those values are then used as the actual
-type-instance. An example would be the C<IF-MIB::ifDescr> subtree.
-L<variables(5)> from the SNMP distribution describes the format of OIDs.
+The meaning of this setting depends on whether B<Table> is set to I<true> or
+I<false>.
 
-If B<Table> is set to I<true> and B<Instance> is omitted, then "SUBID" will be
-used as the instance.
+If B<Table> is set to I<true>, option behaves as B<TypeInstanceOID>.
+If B<Table> is set to I<false>, option behaves as B<TypeInstance>.
 
-If B<Table> is set to I<false> the actual string configured for I<Instance> is
-copied into the value-list. In this case I<Instance> may be empty, i.E<nbsp>e.
-"".
+Note what B<Table> option must be set before setting B<Instance>.
 
 =item B<InstancePrefix> I<String>
 
@@ -204,9 +249,9 @@ This value is not applied to counter-values.
 
 =item B<Ignore> I<Value> [, I<Value> ...]
 
-The ignore values allows to ignore Instances based on their name and the patterns
-specified by the various values you've entered. The match is a glob-type shell
-matching.
+The ignore values allows one to ignore Instances based on their name and the
+patterns specified by the various values you've entered. The match is a
+glob-type shell matching.
 
 =item B<InvertMatch> I<true|false(default)>
 
@@ -228,7 +273,8 @@ stored by collectd.
 
 =item B<Address> I<IP-Address>|I<Hostname>
 
-Set the address to connect to.
+Set the address to connect to. Address may include transport specifier and/or
+port number.
 
 =item B<Version> B<1>|B<2>|B<3>
 
@@ -280,6 +326,15 @@ switches, embedded devices, rack monitoring systems and so on. Since the
 B<Step> of generated RRD files depends on this setting it's wise to select a
 reasonable value once and never change it.
 
+=item B<Timeout> I<Seconds>
+
+How long to wait for a response. The C<Net-SNMP> library default is 1 second.
+
+=item B<Retries> I<Integer>
+
+The number of times that a query should be retried after the Timeout expires.
+The C<Net-SNMP> library default is 5.
+
 =back
 
 =head1 SEE ALSO