X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fcollectd-snmp.pod;h=db955d699574b6eb03201ab0245d6c66549202f8;hb=06d7fbe8bb299e76cac532378e7b1999495979dc;hp=c19b8a00c0cb03d8f6f449e049e40387f7f76456;hpb=e71b0716ca4c0a3df8ffae073d66535a7f61d70e;p=collectd.git diff --git a/src/collectd-snmp.pod b/src/collectd-snmp.pod index c19b8a00..db955d69 100644 --- a/src/collectd-snmp.pod +++ b/src/collectd-snmp.pod @@ -1,3 +1,5 @@ +=encoding UTF-8 + =head1 NAME collectd-snmp - Documentation of collectd's C @@ -11,12 +13,14 @@ collectd-snmp - Documentation of collectd's C Type "voltage" Table false Instance "input_line1" + Scale 0.1 Values "SNMPv2-SMI::enterprises.6050.5.4.1.1.2.1" Type "users" Table false Instance "" + Shift -1 Values "HOST-RESOURCES-MIB::hrSystemNumUsers.0" @@ -31,6 +35,7 @@ collectd-snmp - Documentation of collectd's C Version 1 Community "community_string" Collect "std_traffic" + Interval 120 Address "192.168.0.42" @@ -38,11 +43,23 @@ collectd-snmp - Documentation of collectd's C Community "another_string" Collect "std_traffic" "hr_users" + + Address "192.168.0.7" + Version 3 + SecurityLevel "authPriv" + Username "cosmo" + AuthProtocol "SHA" + AuthPassphrase "setec_astronomy" + PrivacyProtocol "AES" + PrivacyPassphrase "too_many_secrets" + Collect "std_traffic" + Address "192.168.0.3" Version 1 Community "more_communities" Collect "powerplus_voltge_input" + Interval 300 @@ -54,11 +71,18 @@ internal format and dispatches them. Depending on the write plugins you have loaded they may be written to disk or submitted to another instance or whatever you configured. +Because querying a host via SNMP may produce a timeout multiple threads are +used to query hosts in parallel. Depending on the number of hosts between one +and ten threads are used. + =head1 CONFIGURATION Since the aim of the C is to provide a generic interface to SNMP, it's configuration is not trivial and may take some time. +Since the C library is used you can use all the environment variables +that are interpreted by that package. See L for more details. + There are two types of blocks that can be contained in the CPluginEsnmpE> block: B and B: @@ -74,20 +98,40 @@ queried. The following options can be set: collectd's type that is to be used, e.Eg. "if_octets" for interface traffic or "users" for a user count. The types are read from the B (see L), so you may want to check for which types are -defined. +defined. See L for a description of the format of this file. =item B I Define if this is a single list of values or a table of values. The difference -is that when querying a list of values from SNMP that data is going to be -dispatched as one value-list to the daemon (i.Ee. one RRD file will be -created). If the correcponding data-set needs more than one value (has more -than one data-source) you will still need to configure more than one B -(see below). - -If B
is set to I then the plugin will search the entire subtree -and dispatch all values it can find. This is handy for the typical SNMP -tables, such as the interface table (C). +is the following: + +When B
is set to B, the OIDs given to B (see below) are +queried using the C SNMP command (see L) and transmitted to +collectd. B value list is dispatched and, eventually, one file will be +written. + +When B
is set to B, the OIDs given to B (see below) are +queried using the C SNMP command until the subtree is left. After all +the lists (think: all columns of the table) have been read B values +sets will be dispatches and, eventually, several files will be written. If you +configure a B (see above) which needs more than one data source (for +example C which needs C and C) you will need to specify more +than one (two, in the example case) OIDs with the B option. This has +nothing to do with the B
setting. + +For example, if you want to query the number of users on a system, you can use +C. This is one value and belongs to one +value list, therefore B
must be set to B. Please note that, in +this case, you have to include the sequence number (zero in this case) in the +OID. + +Counter example: If you want to query the interface table provided by the +C, e.Eg. the bytes transmitted. There are potentially many +interfaces, so you will want to set B
to B. Because the +C type needs two values, received and transmitted bytes, you need to +specify two OIDs in the B setting, in this case likely +C and C. But, this is because of +the B setting, not the B
setting. Since the semantic of B and B depends on this setting you need to set it before setting them. Doing vice verse will result in undefined @@ -96,17 +140,34 @@ behavior. =item B I Sets the type-instance of the values that are dispatched. The meaning of this -setting depends on wether B
is set to I or I: +setting depends on whether B
is set to I or I: If B
is set to I, I is interpreted as an SNMP-prefix -that will return a list of strings. Those strings are then used as the actual +that will return a list of values. Those values are then used as the actual type-instance. An example would be the C subtree. L from the SNMP distribution describes the format of OIDs. +If B
is set to I and B is omitted, then "SUBID" will be +used as the instance. + If B
is set to I the actual string configured for I is copied into the value-list. In this case I may be empty, i.Ee. "". +=item B I + +If B
is set to I, you may feel the need to add something to the +instance of the files. If set, I is prepended to the instance as +determined by querying the agent. When B
is set to I this option +has no effect. + +The C is an example where you need this setting: It has voltages of +the inlets, outlets and the battery of an UPS. However, it doesn't provide a +descriptive column for these voltages. In this case having 1, 2,E... as +instances is not enough, because the inlet voltages and outlet voltages may +both have the subids 1, 2,E... You can use this setting to distinguish +between the different voltages. + =item B I [I ...] Configures the values to be queried from the SNMP host. The meaning slightly @@ -122,6 +183,37 @@ If B
is set to I, each I must be the OID of exactly one value, e.Eg. C for the third counter of incoming traffic. +=item B I + +The gauge-values returned by the SNMP-agent are multiplied by I. This +is useful when values are transfered 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 I + +I is added to gauge-values returned by the SNMP-agent after they have +been multiplied by any B value. If, for example, a thermometer returns +degrees Kelvin you could specify a shift of B<273.15> here to store values in +degrees Celsius. The default value is, of course, B<0.0>. + +This value is not applied to counter-values. + +=item B I [, I ...] + +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. + +=item B I + +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 @@ -138,14 +230,41 @@ stored by collectd. Set the address to connect to. -=item B B<1>|B<2> +=item B B<1>|B<2>|B<3> -Set the SNMP version to use. When giving B<2> version 2c is actually used. -Version 3 is not supported by this plugin. +Set the SNMP version to use. When giving B<2> version C<2c> is actually used. =item B I -Pass I to the host. +Pass I to the host. (Ignored for SNMPv3). + +=item B I + +Sets the I to use for SNMPv3 security. + +=item B I|I|I + +Selects the security level for SNMPv3 security. + +=item B I + +Sets the I for SNMPv3 security. + +=item B I|I + +Selects the authentication protocol for SNMPv3 security. + +=item B I + +Sets the authentication passphrase for SNMPv3 security. + +=item B I|I + +Selects the privacy (encryption) protocol for SNMPv3 security. + +=item B I + +Sets the privacy (encryption) passphrase for SNMPv3 security. =item B I [I ...] @@ -153,12 +272,15 @@ Defines which values to collect. I refers to one of the B block above. Since the config file is read top-down you need to define the data before using it here. -=back +=item B I -=head1 BUGS +Collect data from this host every I seconds. This option is meant for +devices with not much CPU power, e.Eg. network equipment such as +switches, embedded devices, rack monitoring systems and so on. Since the +B of generated RRD files depends on this setting it's wise to select a +reasonable value once and never change it. -All configured hosts are queried sequencially, so timeouts may cause gaps in -graphs. +=back =head1 SEE ALSO @@ -169,8 +291,9 @@ L, L, L -=head1 AUTHOR +=head1 AUTHORS Florian Forster Eocto@verplant.orgE +Michael Pilat Emike@mikepilat.comE =cut