src/collectd-snmp.pod

   1 =head1 NAME
   2
   3 collectd-snmp - Documentation of collectd's C<snmp plugin>
   4
   5 =head1 SYNOPSIS
   6
   7   LoadPlugin snmp
   8   # ...
   9   <Plugin snmp>
  10     <Data "powerplus_voltge_input">
  11       Type "voltage"
  12       Table false
  13       Instance "input_line1"
  14       Values "SNMPv2-SMI::enterprises.6050.5.4.1.1.2.1"
  15     </Data>
  16     <Data "hr_users">
  17       Type "users"
  18       Table false
  19       Instance ""
  20       Values "HOST-RESOURCES-MIB::hrSystemNumUsers.0"
  21     </Data>
  22     <Data "std_traffic">
  23       Type "if_octets"
  24       Table true
  25       Instance "IF-MIB::ifDescr"
  26       Values "IF-MIB::ifInOctets" "IF-MIB::ifOutOctets"
  27     </Data>
  28
  29     <Host "some.switch.mydomain.org">
  30       Address "192.168.0.2"
  31       Version 1
  32       Community "community_string"
  33       Collect "std_traffic"
  34       Inverval 120
  35     </Host>
  36     <Host "some.server.mydomain.org">
  37       Address "192.168.0.42"
  38       Version 2
  39       Community "another_string"
  40       Collect "std_traffic" "hr_users"
  41     </Host>
  42     <Host "some.ups.mydomain.org">
  43       Address "192.168.0.3"
  44       Version 1
  45       Community "more_communities"
  46       Collect "powerplus_voltge_input"
  47       Interval 300
  48     </Host>
  49   </Plugin>
  50
  51 =head1 DESCRIPTION
  52
  53 The C<snmp plugin> queries other hosts using SNMP, the simple network
  54 management protocol, and translates the value it receives to collectd's
  55 internal format and dispatches them. Depending on the write plugins you have
  56 loaded they may be written to disk or submitted to another instance or
  57 whatever you configured.
  58
  59 =head1 CONFIGURATION
  60
  61 Since the aim of the C<snmp plugin> is to provide a generic interface to SNMP,
  62 it's configuration is not trivial and may take some time.
  63
  64 There are two types of blocks that can be contained in the
  65 C<E<lt>PluginE<nbsp>snmpE<gt>> block: B<Data> and B<Host>:
  66
  67 =head2 The B<Data> block
  68
  69 The B<Data> block defines a list of values or a table of values that are to be
  70 queried. The following options can be set:
  71
  72 =over 4
  73
  74 =item B<Type> I<type>
  75
  76 collectd's type that is to be used, e.E<nbsp>g. "if_octets" for interface
  77 traffic or "users" for a user count. The types are read from the B<TypesDB>
  78 (see L<collectd.conf(5)>), so you may want to check for which types are
  79 defined.
  80
  81 =item B<Table> I<true|false>
  82
  83 Define if this is a single list of values or a table of values. The difference
  84 is that when querying a list of values from SNMP that data is going to be
  85 dispatched as one value-list to the daemon (i.E<nbsp>e.  one RRD file will be
  86 created). If the correcponding data-set needs more than one value (has more
  87 than one data-source) you will still need to configure more than one B<Values>
  88 (see below).
  89
  90 If B<Table> is set to I<true> then the plugin will search the entire subtree
  91 and dispatch all values it can find. This is handy for the typical SNMP
  92 tables, such as the interface table (C<IF-MIB::ifTable>).
  93
  94 Since the semantic of B<Instance> and B<Values> depends on this setting you
  95 need to set it before setting them. Doing vice verse will result in undefined
  96 behavior.
  97
  98 =item B<Instance> I<Instance>
  99
 100 Sets the type-instance of the values that are dispatched. The meaning of this
 101 setting depends on wether B<Table> is set to I<true> or I<false>:
 102
 103 If B<Table> is set to I<true>, I<Instance> is interpreted as an SNMP-prefix
 104 that will return a list of strings. Those strings are then used as the actual
 105 type-instance. An example would be the C<IF-MIB::ifDescr> subtree.
 106 L<variables(5)> from the SNMP distribution describes the format of OIDs.
 107
 108 If B<Table> is set to I<false> the actual string configured for I<Instance> is
 109 copied into the value-list. In this case I<Instance> may be empty, i.E<nbsp>e.
 110 "".
 111
 112 =item B<Values> I<OID> [I<OID> ...]
 113
 114 Configures the values to be queried from the SNMP host. The meaning slightly
 115 changes with the B<Table> setting. L<variables(5)> from the SNMP distribution
 116 describes the format of OIDs.
 117
 118 If B<Table> is set to I<true>, each I<OID> must be the prefix of all the
 119 values to query, e.E<nbsp>g. C<IF-MIB::ifInOctets> for all the counters of
 120 incoming traffic. This subtree is walked (using C<GETNEXT>) until a value from
 121 outside the subtree is returned.
 122
 123 If B<Table> is set to I<false>, each I<OID> must be the OID of exactly one
 124 value, e.E<nbsp>g. C<IF-MIB::ifInOctets.3> for the third counter of incoming
 125 traffic.
 126
 127 =back
 128
 129 =head2 The Host block
 130
 131 The B<Host> block defines which hosts to query, which SNMP community and
 132 version to use and which of the defined B<Data> to query.
 133
 134 The argument passed to the B<Host> block is used as the hostname in the data
 135 stored by collectd.
 136
 137 =over 4
 138
 139 =item B<Address> I<IP-Address>|I<Hostname>
 140
 141 Set the address to connect to.
 142
 143 =item B<Version> B<1>|B<2>
 144
 145 Set the SNMP version to use. When giving B<2> version 2c is actually used.
 146 Version 3 is not supported by this plugin.
 147
 148 =item B<Community> I<Community>
 149
 150 Pass I<Community> to the host.
 151
 152 =item B<Collect> I<Data> [I<Data> ...]
 153
 154 Defines which values to collect. I<Data> refers to one of the B<Data> block
 155 above. Since the config file is read top-down you need to define the data
 156 before using it here.
 157
 158 =item B<Interval> I<Seconds>
 159
 160 Collect data from this host every I<Seconds> seconds. This value needs to be a
 161 multiple of the global B<Interval> setting and, if it is not, will be rounded
 162 B<down> to one and a warning is logged in this case. So if your global
 163 B<Interval> is set to I<10> and you configure I<25> here, it's rounded down to
 164 I<20>. By default the global B<Interval> setting will be used.
 165
 166 This option is meant for devices with not much CPU power, e.E<nbsp>g. network
 167 equipment such as switches, embedded devices, rack monitoring systems and so
 168 on. Since the B<Step> of generated RRD files depends on this setting it's
 169 wise to select a reasonable value once and never change it.
 170
 171 =back
 172
 173 =head1 BUGS
 174
 175 All configured hosts are queried sequencially, so timeouts may cause gaps in
 176 graphs.
 177
 178 =head1 SEE ALSO
 179
 180 L<collectd(1)>,
 181 L<collectd.conf(5)>,
 182 L<snmpget(1)>,
 183 L<snmpgetnext(1)>,
 184 L<variables(5)>,
 185 L<unix(7)>
 186
 187 =head1 AUTHOR
 188
 189 Florian Forster E<lt>octo@verplant.orgE<gt>
 190
 191 =cut