# ...
<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>
Community "community_string"
Collect "std_traffic"
Interval 120
+ Timeout 10
+ Retries 1
</Host>
<Host "some.server.mydomain.org">
Address "192.168.0.42"
Community "another_string"
Collect "std_traffic" "hr_users"
</Host>
+ <Host "secure.router.mydomain.org">
+ Address "192.168.0.7:165"
+ Version 3
+ SecurityLevel "authPriv"
+ Username "cosmo"
+ AuthProtocol "SHA"
+ AuthPassphrase "setec_astronomy"
+ PrivacyProtocol "AES"
+ PrivacyPassphrase "too_many_secrets"
+ 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>
=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.
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>
=item B<Scale> I<Value>
The gauge-values returned by the SNMP-agent are multiplied by I<Value>. This
-is useful when values are transfered as a fixed point real number. For example,
+is useful when values are transferred as a fixed point real number. For example,
thermometers may transfer B<243> but actually mean B<24.3>, so you can specify
a scale value of B<0.1> to correct this. The default value is, of course,
B<1.0>.
This value is not applied to counter-values.
+=item B<Ignore> I<Value> [, I<Value> ...]
+
+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)>
+
+The invertmatch value should be use in combination of the Ignore option.
+It changes the behaviour of the Ignore option, from a blacklist behaviour
+when InvertMatch is set to false, to a whitelist when specified to true.
+
=back
=head2 The Host block
=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>
+=item B<Version> B<1>|B<2>|B<3>
Set the SNMP version to use. When giving B<2> version C<2c> is actually used.
-Version 3 is not supported by this plugin.
=item B<Community> I<Community>
-Pass I<Community> to the host.
+Pass I<Community> to the host. (Ignored for SNMPv3).
+
+=item B<Username> I<Username>
+
+Sets the I<Username> to use for SNMPv3 security.
+
+=item B<SecurityLevel> I<authPriv>|I<authNoPriv>|I<noAuthNoPriv>
+
+Selects the security level for SNMPv3 security.
+
+=item B<Context> I<Context>
+
+Sets the I<Context> for SNMPv3 security.
+
+=item B<AuthProtocol> I<MD5>|I<SHA>
+
+Selects the authentication protocol for SNMPv3 security.
+
+=item B<AuthPassphrase> I<Passphrase>
+
+Sets the authentication passphrase for SNMPv3 security.
+
+=item B<PrivacyProtocol> I<AES>|I<DES>
+
+Selects the privacy (encryption) protocol for SNMPv3 security.
+
+=item B<PrivacyPassphrase> I<Passphrase>
+
+Sets the privacy (encryption) passphrase for SNMPv3 security.
=item B<Collect> I<Data> [I<Data> ...]
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
L<variables(5)>,
L<unix(7)>
-=head1 AUTHOR
+=head1 AUTHORS
-Florian Forster E<lt>octo@verplant.orgE<gt>
+Florian Forster E<lt>octo@collectd.orgE<gt>
+Michael Pilat E<lt>mike@mikepilat.comE<gt>
=cut
projects / collectd.git / blobdiff