![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/src/collectd-snmp.5 b/src/collectd-snmp.5
--- /dev/null
+++ b/src/collectd-snmp.5
@@ -0,0 +1,400 @@
+.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+. ds C`
+. ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{
+. if \nF \{
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. if !\nF==2 \{
+. nr % 0
+. nr F 2
+. \}
+. \}
+.\}
+.rr rF
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "COLLECTD-SNMP 5"
+.TH COLLECTD-SNMP 5 "2015-03-10" "5.4.1.805.g42e4d6c" "collectd"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+collectd\-snmp \- Documentation of collectd's "snmp plugin"
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 10
+\& LoadPlugin snmp
+\& # ...
+\& <Plugin snmp>
+\& <Data "powerplus_voltge_input">
+\& Type "voltage"
+\& Table false
+\& Instance "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 ""
+\& Shift \-1
+\& Values "HOST\-RESOURCES\-MIB::hrSystemNumUsers.0"
+\& </Data>
+\& <Data "std_traffic">
+\& Type "if_octets"
+\& Table true
+\& Instance "IF\-MIB::ifDescr"
+\& Values "IF\-MIB::ifInOctets" "IF\-MIB::ifOutOctets"
+\& </Data>
+\&
+\& <Host "some.switch.mydomain.org">
+\& Address "192.168.0.2"
+\& Version 1
+\& Community "community_string"
+\& Collect "std_traffic"
+\& Interval 120
+\& </Host>
+\& <Host "some.server.mydomain.org">
+\& Address "192.168.0.42"
+\& Version 2
+\& Community "another_string"
+\& Collect "std_traffic" "hr_users"
+\& </Host>
+\& <Host "secure.router.mydomain.org">
+\& 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"
+\& </Host>
+\& <Host "some.ups.mydomain.org">
+\& Address "192.168.0.3"
+\& Version 1
+\& Community "more_communities"
+\& Collect "powerplus_voltge_input"
+\& Interval 300
+\& </Host>
+\& </Plugin>
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The \f(CW\*(C`snmp plugin\*(C'\fR queries other hosts using \s-1SNMP,\s0 the simple network
+management protocol, and translates the value it receives to collectd's
+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.
+.PP
+Because querying a host via \s-1SNMP\s0 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.
+.SH "CONFIGURATION"
+.IX Header "CONFIGURATION"
+Since the aim of the \f(CW\*(C`snmp plugin\*(C'\fR is to provide a generic interface to \s-1SNMP,\s0
+it's configuration is not trivial and may take some time.
+.PP
+Since the \f(CW\*(C`Net\-SNMP\*(C'\fR library is used you can use all the environment variables
+that are interpreted by that package. See \fIsnmpcmd\fR\|(1) for more details.
+.PP
+There are two types of blocks that can be contained in the
+\&\f(CW\*(C`<Plugin\ snmp>\*(C'\fR block: \fBData\fR and \fBHost\fR:
+.SS "The \fBData\fP block"
+.IX Subsection "The Data block"
+The \fBData\fR block defines a list of values or a table of values that are to be
+queried. The following options can be set:
+.IP "\fBType\fR \fItype\fR" 4
+.IX Item "Type type"
+collectd's type that is to be used, e.\ g. \*(L"if_octets\*(R" for interface
+traffic or \*(L"users\*(R" for a user count. The types are read from the \fBTypesDB\fR
+(see \fIcollectd.conf\fR\|(5)), so you may want to check for which types are
+defined. See \fItypes.db\fR\|(5) for a description of the format of this file.
+.IP "\fBTable\fR \fItrue|false\fR" 4
+.IX Item "Table true|false"
+Define if this is a single list of values or a table of values. The difference
+is the following:
+.Sp
+When \fBTable\fR is set to \fBfalse\fR, the OIDs given to \fBValues\fR (see below) are
+queried using the \f(CW\*(C`GET\*(C'\fR \s-1SNMP\s0 command (see \fIsnmpget\fR\|(1)) and transmitted to
+collectd. \fBOne\fR value list is dispatched and, eventually, one file will be
+written.
+.Sp
+When \fBTable\fR is set to \fBtrue\fR, the OIDs given to \fBValues\fR (see below) are
+queried using the \f(CW\*(C`GETNEXT\*(C'\fR \s-1SNMP\s0 command until the subtree is left. After all
+the lists (think: all columns of the table) have been read \fBseveral\fR values
+sets will be dispatches and, eventually, several files will be written. If you
+configure a \fBType\fR (see above) which needs more than one data source (for
+example \f(CW\*(C`if_octets\*(C'\fR which needs \f(CW\*(C`rx\*(C'\fR and \f(CW\*(C`tx\*(C'\fR) you will need to specify more
+than one (two, in the example case) OIDs with the \fBValues\fR option. This has
+nothing to do with the \fBTable\fR setting.
+.Sp
+For example, if you want to query the number of users on a system, you can use
+\&\f(CW\*(C`HOST\-RESOURCES\-MIB::hrSystemNumUsers.0\*(C'\fR. This is one value and belongs to one
+value list, therefore \fBTable\fR must be set to \fBfalse\fR. Please note that, in
+this case, you have to include the sequence number (zero in this case) in the
+\&\s-1OID.\s0
+.Sp
+Counter example: If you want to query the interface table provided by the
+\&\f(CW\*(C`IF\-MIB\*(C'\fR, e.\ g. the bytes transmitted. There are potentially many
+interfaces, so you will want to set \fBTable\fR to \fBtrue\fR. Because the
+\&\f(CW\*(C`if_octets\*(C'\fR type needs two values, received and transmitted bytes, you need to
+specify two OIDs in the \fBValues\fR setting, in this case likely
+\&\f(CW\*(C`IF\-MIB::ifHCInOctets\*(C'\fR and \f(CW\*(C`IF\-MIB::ifHCOutOctets\*(C'\fR. But, this is because of
+the \fBType\fR setting, not the \fBTable\fR setting.
+.Sp
+Since the semantic of \fBInstance\fR and \fBValues\fR depends on this setting you
+need to set it before setting them. Doing vice verse will result in undefined
+behavior.
+.IP "\fBInstance\fR \fIInstance\fR" 4
+.IX Item "Instance Instance"
+Sets the type-instance of the values that are dispatched. The meaning of this
+setting depends on whether \fBTable\fR is set to \fItrue\fR or \fIfalse\fR:
+.Sp
+If \fBTable\fR is set to \fItrue\fR, \fIInstance\fR 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 \f(CW\*(C`IF\-MIB::ifDescr\*(C'\fR subtree.
+\&\fIvariables\fR\|(5) from the \s-1SNMP\s0 distribution describes the format of OIDs.
+.Sp
+If \fBTable\fR is set to \fItrue\fR and \fBInstance\fR is omitted, then \*(L"\s-1SUBID\*(R"\s0 will be
+used as the instance.
+.Sp
+If \fBTable\fR is set to \fIfalse\fR the actual string configured for \fIInstance\fR is
+copied into the value-list. In this case \fIInstance\fR may be empty, i.\ e.
+"".
+.IP "\fBInstancePrefix\fR \fIString\fR" 4
+.IX Item "InstancePrefix String"
+If \fBTable\fR is set to \fItrue\fR, you may feel the need to add something to the
+instance of the files. If set, \fIString\fR is prepended to the instance as
+determined by querying the agent. When \fBTable\fR is set to \fIfalse\fR this option
+has no effect.
+.Sp
+The \f(CW\*(C`UPS\-MIB\*(C'\fR is an example where you need this setting: It has voltages of
+the inlets, outlets and the battery of an \s-1UPS.\s0 However, it doesn't provide a
+descriptive column for these voltages. In this case having 1, 2,\ ... as
+instances is not enough, because the inlet voltages and outlet voltages may
+both have the subids 1, 2,\ ... You can use this setting to distinguish
+between the different voltages.
+.IP "\fBValues\fR \fI\s-1OID\s0\fR [\fI\s-1OID\s0\fR ...]" 4
+.IX Item "Values OID [OID ...]"
+Configures the values to be queried from the \s-1SNMP\s0 host. The meaning slightly
+changes with the \fBTable\fR setting. \fIvariables\fR\|(5) from the \s-1SNMP\s0 distribution
+describes the format of OIDs.
+.Sp
+If \fBTable\fR is set to \fItrue\fR, each \fI\s-1OID\s0\fR must be the prefix of all the
+values to query, e.\ g. \f(CW\*(C`IF\-MIB::ifInOctets\*(C'\fR for all the counters of
+incoming traffic. This subtree is walked (using \f(CW\*(C`GETNEXT\*(C'\fR) until a value from
+outside the subtree is returned.
+.Sp
+If \fBTable\fR is set to \fIfalse\fR, each \fI\s-1OID\s0\fR must be the \s-1OID\s0 of exactly one
+value, e.\ g. \f(CW\*(C`IF\-MIB::ifInOctets.3\*(C'\fR for the third counter of incoming
+traffic.
+.IP "\fBScale\fR \fIValue\fR" 4
+.IX Item "Scale Value"
+The gauge-values returned by the SNMP-agent are multiplied by \fIValue\fR. This
+is useful when values are transferred as a fixed point real number. For example,
+thermometers may transfer \fB243\fR but actually mean \fB24.3\fR, so you can specify
+a scale value of \fB0.1\fR to correct this. The default value is, of course,
+\&\fB1.0\fR.
+.Sp
+This value is not applied to counter-values.
+.IP "\fBShift\fR \fIValue\fR" 4
+.IX Item "Shift Value"
+\&\fIValue\fR is added to gauge-values returned by the SNMP-agent after they have
+been multiplied by any \fBScale\fR value. If, for example, a thermometer returns
+degrees Kelvin you could specify a shift of \fB273.15\fR here to store values in
+degrees Celsius. The default value is, of course, \fB0.0\fR.
+.Sp
+This value is not applied to counter-values.
+.IP "\fBIgnore\fR \fIValue\fR [, \fIValue\fR ...]" 4
+.IX Item "Ignore Value [, 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.
+.IP "\fBInvertMatch\fR \fItrue|false(default)\fR" 4
+.IX Item "InvertMatch 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.
+.SS "The Host block"
+.IX Subsection "The Host block"
+The \fBHost\fR block defines which hosts to query, which \s-1SNMP\s0 community and
+version to use and which of the defined \fBData\fR to query.
+.PP
+The argument passed to the \fBHost\fR block is used as the hostname in the data
+stored by collectd.
+.IP "\fBAddress\fR \fIIP-Address\fR|\fIHostname\fR" 4
+.IX Item "Address IP-Address|Hostname"
+Set the address to connect to.
+.IP "\fBVersion\fR \fB1\fR|\fB2\fR|\fB3\fR" 4
+.IX Item "Version 1|2|3"
+Set the \s-1SNMP\s0 version to use. When giving \fB2\fR version \f(CW\*(C`2c\*(C'\fR is actually used.
+.IP "\fBCommunity\fR \fICommunity\fR" 4
+.IX Item "Community Community"
+Pass \fICommunity\fR to the host. (Ignored for SNMPv3).
+.IP "\fBUsername\fR \fIUsername\fR" 4
+.IX Item "Username Username"
+Sets the \fIUsername\fR to use for SNMPv3 security.
+.IP "\fBSecurityLevel\fR \fIauthPriv\fR|\fIauthNoPriv\fR|\fInoAuthNoPriv\fR" 4
+.IX Item "SecurityLevel authPriv|authNoPriv|noAuthNoPriv"
+Selects the security level for SNMPv3 security.
+.IP "\fBContext\fR \fIContext\fR" 4
+.IX Item "Context Context"
+Sets the \fIContext\fR for SNMPv3 security.
+.IP "\fBAuthProtocol\fR \fI\s-1MD5\s0\fR|\fI\s-1SHA\s0\fR" 4
+.IX Item "AuthProtocol MD5|SHA"
+Selects the authentication protocol for SNMPv3 security.
+.IP "\fBAuthPassphrase\fR \fIPassphrase\fR" 4
+.IX Item "AuthPassphrase Passphrase"
+Sets the authentication passphrase for SNMPv3 security.
+.IP "\fBPrivacyProtocol\fR \fI\s-1AES\s0\fR|\fI\s-1DES\s0\fR" 4
+.IX Item "PrivacyProtocol AES|DES"
+Selects the privacy (encryption) protocol for SNMPv3 security.
+.IP "\fBPrivacyPassphrase\fR \fIPassphrase\fR" 4
+.IX Item "PrivacyPassphrase Passphrase"
+Sets the privacy (encryption) passphrase for SNMPv3 security.
+.IP "\fBCollect\fR \fIData\fR [\fIData\fR ...]" 4
+.IX Item "Collect Data [Data ...]"
+Defines which values to collect. \fIData\fR refers to one of the \fBData\fR block
+above. Since the config file is read top-down you need to define the data
+before using it here.
+.IP "\fBInterval\fR \fISeconds\fR" 4
+.IX Item "Interval Seconds"
+Collect data from this host every \fISeconds\fR seconds. This option is meant for
+devices with not much \s-1CPU\s0 power, e.\ g. network equipment such as
+switches, embedded devices, rack monitoring systems and so on. Since the
+\&\fBStep\fR of generated \s-1RRD\s0 files depends on this setting it's wise to select a
+reasonable value once and never change it.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIcollectd\fR\|(1),
+\&\fIcollectd.conf\fR\|(5),
+\&\fIsnmpget\fR\|(1),
+\&\fIsnmpgetnext\fR\|(1),
+\&\fIvariables\fR\|(5),
+\&\fIunix\fR\|(7)
+.SH "AUTHORS"
+.IX Header "AUTHORS"
+Florian Forster <octo@collectd.org>
+Michael Pilat <mike@mikepilat.com>