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