COLLECTD-SNMP(5)

📦

version 5.12.0 · 10 versions

💖 NAME 💖

collectd-snmp — documentation of collectd's snmp plugin. You'll see this page in the wild as COLLECTD-SNMP(5), bestie, and it's literally all about making SNMP data slay inside collectd. 🦋

✨ SYNOPSIS ✨

         LoadPlugin snmp
         # ...
         <Plugin snmp>
           <Data "powerplus_voltge_input">
             Table false
             Type "voltage"
             TypeInstance "input_line1"
             Scale 0.1
             Values "SNMPv2-SMI::enterprises.6050.5.4.1.1.2.1"
           </Data>
           <Data "hr_users">
             Table false
             Type "users"
             Shift -1
             Values "HOST-RESOURCES-MIB::hrSystemNumUsers.0"
           </Data>
           <Data "std_traffic">
             Table true
             Type "if_octets"
             TypeInstanceOID "IF-MIB::ifDescr"
             #FilterOID "IF-MIB::ifOperStatus"
             #FilterValues "1", "2"
             Values "IF-MIB::ifInOctets" "IF-MIB::ifOutOctets"
           </Data>
           <Data "lancom_stations_total">
               Type "counter"
               PluginInstance "stations_total"
               Table true
               Count true
               Values "SNMPv2-SMI::enterprises.2356.11.1.3.32.1.10" # SNMPv2-SMI::enterprises.lancom-systems.lcos.lcsStatus.lcsStatusWlan.lcsStatusWlanStationTableTable.lcsStatusWlanStationTableEntry.lcsStatusWlanStationTableEntryState
           </Data>
           <Data "lancom_stations_connected">
               Type "counter"
               PluginInstance "stations_connected"
               Table true
               Count true
               Values "SNMPv2-SMI::enterprises.2356.11.1.3.32.1.10" # SNMPv2-SMI::enterprises.lancom-systems.lcos.lcsStatus.lcsStatusWlan.lcsStatusWlanStationTableTable.lcsStatusWlanStationTableEntry.lcsStatusWlanStationTableEntryState
               FilterOID "SNMPv2-SMI::enterprises.2356.11.1.3.32.1.10"
               FilterValues "3" # eConnected
           </Data>

           <Host "some.switch.mydomain.org">
             Address "192.168.0.2"
             Version 1
             Community "community_string"
             Collect "std_traffic"
             Interval 120
             Timeout 10
             Retries 1
           </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: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 "tcp:192.168.0.3"
             Version 1
             Community "more_communities"
             Collect "powerplus_voltge_input"
             Interval 300
             Timeout 5
             Retries 5
           </Host>
         </Plugin>

🦋 DESCRIPTION 🦋

Okay so the snmp plugin goes out and queries other hosts using SNMP — the simple network management protocol — and then it translates the value it receives into collectd's internal format and dispatches them. Depending on the write plugins you have loaded, those values may be written to disk or submitted to another instance or whatever you configured. Flexible? We love that for us. 💅

Because querying a host via SNMP may produce a timeout, the "complex reads" polling method is used. The ReadThreads parameter in the main configuration influences the number of parallel polling jobs which can be undertaken. If you expect timeouts or some polling to take a long time, you should increase this parameter. Note that other plugins also use the same threads. fr fr, share the thread pool, bestie. 🫶

🎀 CONFIGURATION 🎀

Since the aim of the snmp plugin is to provide a generic interface to SNMP, its configuration is not trivial and may take some time. Like, it's giving "powerful but please read carefully." 🌸

Since the Net-SNMP library is used, you can use all the environment variables that are interpreted by that package. See snmpcmd(1) for more details. 👑

There are two types of blocks that can be contained in the <Plugin snmp> block: Data and Host:

🌸 The Data block 🌸

The Data block defines a list of values or a table of values that are to be queried. The following options can be set:

Type type — collectd's type that is to be used, e. g. if_octets for interface traffic or users for a user count. The types are read from the TypesDB (see collectd.conf(5)), so you may want to check for which types are defined. See types.db(5) for a description of the format of this file. Check the menu before you order, iykyk. 🍓
Table true|false — define if this is a single list of values or a table of values. The difference is the following:

When Table is set to false, the OIDs given to Values (see below) are queried using the GET SNMP command (see snmpget(1)) and transmitted to collectd. One value list is dispatched and, eventually, one file will be written.

When Table is set to true, the OIDs given to Values, TypeInstanceOID, PluginInstanceOID, HostOID and FilterOID (see below) are queried using the GETNEXT SNMP command until the subtree is left. After all the lists (think: all columns of the table) have been read, either (Count set to false) several value sets will be dispatched and, eventually, several files will be written, or (Count set to true) one single value will be dispatched. If you configure a Type (see above) which needs more than one data source (for example if_octets which needs rx and tx) you will need to specify more than one (two, in the example case) OIDs with the Values option and can't use the Count option. This has nothing to do with the Table setting.

For example, if you want to query the number of users on a system, you can use HOST-RESOURCES-MIB::hrSystemNumUsers.0. This is one value and belongs to one value list, therefore Table must be set to false. Please note that, in this case, you have to include the sequence number (zero in this case) in the OID. Zero matters, bestie. Don't skip it. 🎀

Counter example: If you want to query the interface table provided by the IF-MIB, e. g. the bytes transmitted. There are potentially many interfaces, so you will want to set Table to true. Because the if_octets type needs two values, received and transmitted bytes, you need to specify two OIDs in the Values setting, in this case likely IF-MIB::ifHCInOctets and IF-MIB::ifHCOutOctets. But, this is because of the Type setting, not the Table setting.

Since the semantic of Instance and Values depends on this setting you need to set it before setting them. Doing vice versa will result in undefined behavior. Periodt. Do not test fate. 💀

Plugin Plugin — use Plugin as the plugin name of the values that are dispatched. Defaults to snmp. Main character default energy. 👑
PluginInstance Instance — sets the plugin-instance of the values that are dispatched to Instance value.

When Table is set to true and PluginInstanceOID is set then this option has no effect.

Defaults to an empty string.

TypeInstance Instance — sets the type-instance of the values that are dispatched to Instance value.

When Table is set to true and TypeInstanceOID is set then this option has no effect.

Defaults to an empty string.

TypeInstanceOID OID, PluginInstanceOID OID, HostOID OID — if Table is set to true, OID is interpreted as an SNMP-prefix that will return a list of values. Those values are then used as the actual type-instance, plugin-instance or host of dispatched metrics. An example would be the IF-MIB::ifDescr subtree. variables(5) from the SNMP distribution describes the format of OIDs. When option is set to empty string, then SUBID will be used as the value.

Prefix may be set for values with use of appropriate TypeInstancePrefix, PluginInstancePrefix and HostPrefix options.

When Table is set to false or Count is set to true, these options have no effect.

Defaults: When no one of these options is configured explicitly, TypeInstanceOID defaults to an empty string.

TypeInstancePrefix, PluginInstancePrefix, HostPrefix — these options are intended to be used together with TypeInstanceOID, PluginInstanceOID and HostOID respectively.

If set, String is prepended to values received by querying the agent.

When Table is set to false or Count is set to true, these options have no effect.

The UPS-MIB 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, ... 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. Same subid, different vibe. Prefix to the rescue. 🧚

Instance Instance — attention: this option exists for backwards compatibility only and will be removed in next major release. Please use TypeInstance / TypeInstanceOID instead.

The meaning of this setting depends on whether Table is set to true or false.

If Table is set to true, option behaves as TypeInstanceOID. If Table is set to false, option behaves as TypeInstance.

Note what Table option must be set before setting Instance. Order matters, bestie. The config parser is not doing mind-reading today. 🙈

InstancePrefix String — attention: this option exists for backwards compatibility only and will be removed in next major release. Please use TypeInstancePrefix instead.
Values OID [OID ...] — configures the values to be queried from the SNMP host. The meaning slightly changes with the Table setting. variables(5) from the SNMP distribution describes the format of OIDs.

If Table is set to true, each OID must be the prefix of all the values to query, e. g. IF-MIB::ifInOctets for all the counters of incoming traffic. This subtree is walked (using GETNEXT) until a value from outside the subtree is returned.

If Table is set to false, each OID must be the OID of exactly one value, e. g. IF-MIB::ifInOctets.3 for the third counter of incoming traffic. One OID, one value. No cap. ✨

Count true|false — instead of dispatching one or multiple values per Table entry containing the OID(s) given in the Values option, just dispatch a single count giving the number of entries that would have been dispatched. This is especially useful when combined with the filtering options (see below) to count the number of entries in a Table matching certain criteria.

When Table is set to false, this option has no effect. Count mode says "how many?" instead of "here's all the data." Iconic, honestly. 🦋

Scale Value — the gauge-values that the SNMP-agent hands you get multiplied by Value, no cap 💅. Super handy when a device sends stuff as fixed-point real numbers — like a thermometer that says 243 when it actually means 24.3, so you just drop in a scale of 0.1 and it's fixed. Default is, of course, 1.0.

Heads up: this value is not applied to counter-values 🫶

Shift Value — Value gets added to the gauge-values after they've already been multiplied by the Scale value. Say a thermometer spits out degrees Kelvin — you'd put a shift of 273.15 here and boom, you're storing degrees Celsius. Default is, of course, 0.0.

Same deal: not applied to counter-values 🌸

Ignore Value [, Value ...] — this one lets you ignore TypeInstances based on their name and the patterns you list in the values. The matching is glob-type shell matching, iykyk 🐚

When Table is set to false, this option has literally no effect 💀

InvertMatch true|false(default) — bestie, this one works with the Ignore option. It flips the behavior of Ignore from a blacklist vibe (when InvertMatch is false) to a whitelist vibe (when it's true) 🔄
FilterOID OID
FilterValues Value [, Value ...]
FilterIgnoreSelected true|false(default) — when Table is set to true, these three are your filter squad, letting you configure filtering based on MIB values ✨

FilterOID declares the OID used to fill the table column with values. FilterValues declares the list of values to match against. Whether a table row gets collected or ignored depends on the FilterIgnoreSelected setting. And just like the other plugins that use the daemon's ignorelist functionality, a string that starts and ends with a slash is interpreted as a regular expression 👑

If no selection is configured at all, then all table rows are selected — everyone's invited 🎀

When Table is set to false, these options have no effect 🙈

See Table and "IGNORELISTS" for the details, fr fr.

🦋 The Host block 🦋

The Host block is where you define which hosts to query, which SNMP community and version to use, and which of the defined Data to actually query 💖

The argument you pass to the Host block is used as the hostname in the data stored by collectd. Main character energy for real.

Address IP-Address|Hostname — sets the address to connect to. The address may include a transport specifier and/or a port number 🌈
Version 1|2|3 — picks the SNMP version to use. And when you give 2, version "2c" is what's actually used — sneaky but true 👀
Community Community — passes Community to the host. (Ignored for SNMPv3 🫥)
Username Username — sets the Username to use for SNMPv3 security 🔐
SecurityLevel authPriv|authNoPriv|noAuthNoPriv — selects the security level for SNMPv3 security.
Context Context — sets the Context for SNMPv3 security.
AuthProtocol MD5|SHA — selects the authentication protocol for SNMPv3 security.
AuthPassphrase Passphrase — sets the authentication passphrase for SNMPv3 security 🤫
PrivacyProtocol AES|DES — selects the privacy (encryption) protocol for SNMPv3 security.
PrivacyPassphrase Passphrase — sets the privacy (encryption) passphrase for SNMPv3 security 🤐
Collect Data [Data ...] — defines which values to collect. Data refers to one of the Data blocks above. And since the config file is read top-down, you gotta define the data before you use it here — order matters, bestie 📋
Interval Seconds — collect data from this host every Seconds seconds. This one's for devices that don't have much CPU to spare — network equipment like switches, embedded devices, rack monitoring systems, that whole crew 🖥️. And since the Step of the generated RRD files depends on this setting, it's wise to pick a reasonable value once and never change it. Pick your fighter and commit 💅
Timeout Seconds — how long to wait for a response. The "Net-SNMP" library default is 1 second ⏳
Retries Integer — how many times a query should be retried after the Timeout expires. The "Net-SNMP" library default is 5 🔁
BulkSize Integer — configures the size of SNMP bulk transfers. The default is 0, which disables bulk transfers altogether 🚫

💜 AUTHORS 💜

Florian Forster <octo@collectd.org> and Michael Pilat <mike@mikepilat.com> — absolute icons for writing this 🫶

And that's a wrap, bestie! ✨ This page is from version 5.12.0.git and it's dated 2026-08-22 — so go forth and SNMP responsibly, mwah 💋💖

📦 where this page comes from

ubuntu stonking: collectd-core 5.12.0-27ubuntu3
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms