dom
/
telegraf
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Rewrite documentation for snmp input (#6802)

This commit is contained in:
Daniel Nelson 2019-12-30 11:33:32 -08:00 committed by GitHub
parent f035d44fe1
commit c325c94a96
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 278 additions and 381 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
plugins/inputs/snmp/CONFIG-EXAMPLES.md
View File

@ -1,65 +0,0 @@
Here are a few configuration examples for different use cases.
### Switch/router interface metrics
This setup will collect data on all interfaces from three different tables, `IF-MIB::ifTable`, `IF-MIB::ifXTable` and `EtherLike-MIB::dot3StatsTable`. It will also add the name from `IF-MIB::ifDescr` and use that as a tag. Depending on your needs and preferences you can easily use `IF-MIB::ifName` or `IF-MIB::ifAlias` instead or in addition. The values of these are typically:
IF-MIB::ifName = Gi0/0/0
IF-MIB::ifDescr = GigabitEthernet0/0/0
IF-MIB::ifAlias = ### LAN ###
This configuration also collects the hostname from the device (`RFC1213-MIB::sysName.0`) and adds as a tag. So each metric will both have the configured host/IP as `agent_host` as well as the device self-reported hostname as `hostname` and the name of the host that has collected these metrics as `host`.
Here is the configuration that you add to your `telegraf.conf`:
```
[[inputs.snmp]]
agents = [ "host.example.com" ]
version = 2
community = "public"
[[inputs.snmp.field]]
name = "hostname"
oid = "RFC1213-MIB::sysName.0"
is_tag = true
[[inputs.snmp.field]]
name = "uptime"
oid = "DISMAN-EXPRESSION-MIB::sysUpTimeInstance"
# IF-MIB::ifTable contains counters on input and output traffic as well as errors and discards.
[[inputs.snmp.table]]
name = "interface"
inherit_tags = [ "hostname" ]
oid = "IF-MIB::ifTable"
# Interface tag - used to identify interface in metrics database
[[inputs.snmp.table.field]]
name = "ifDescr"
oid = "IF-MIB::ifDescr"
is_tag = true
# IF-MIB::ifXTable contains newer High Capacity (HC) counters that do not overflow as fast for a few of the ifTable counters
[[inputs.snmp.table]]
name = "interface"
inherit_tags = [ "hostname" ]
oid = "IF-MIB::ifXTable"
# Interface tag - used to identify interface in metrics database
[[inputs.snmp.table.field]]
name = "ifDescr"
oid = "IF-MIB::ifDescr"
is_tag = true
# EtherLike-MIB::dot3StatsTable contains detailed ethernet-level information about what kind of errors have been logged on an interface (such as FCS error, frame too long, etc)
[[inputs.snmp.table]]
name = "interface"
inherit_tags = [ "hostname" ]
oid = "EtherLike-MIB::dot3StatsTable"
# Interface tag - used to identify interface in metrics database
[[inputs.snmp.table.field]]
name = "ifDescr"
oid = "IF-MIB::ifDescr"
is_tag = true
```

53
plugins/inputs/snmp/DEBUGGING.md
View File

@ -1,53 +0,0 @@
# Debugging & Testing SNMP Issues
### Install net-snmp on your system:
Mac:
```
brew install net-snmp
```
### Run an SNMP simulator docker image to get a full MIB on port 161:
```
docker run -d -p 161:161/udp xeemetric/snmp-simulator
```
### snmpget:
snmpget corresponds to the inputs.snmp.field configuration.
```bash
$ # get an snmp field with fully-qualified MIB name.
$ snmpget -v2c -c public localhost:161 system.sysUpTime.0
DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (1643) 0:00:16.43
$ # get an snmp field, outputting the numeric OID.
$ snmpget -On -v2c -c public localhost:161 system.sysUpTime.0
.1.3.6.1.2.1.1.3.0 = Timeticks: (1638) 0:00:16.38
```
### snmptranslate:
snmptranslate can be used to translate an OID to a MIB name:
```bash
$ snmptranslate .1.3.6.1.2.1.1.3.0
DISMAN-EVENT-MIB::sysUpTimeInstance
```
And to convert a partial MIB name to a fully qualified one:
```bash
$ snmptranslate -IR sysUpTime.0
DISMAN-EVENT-MIB::sysUpTimeInstance
```
And to convert a MIB name to an OID:
```bash
$ snmptranslate -On -IR system.sysUpTime.0
.1.3.6.1.2.1.1.3.0
```

329
plugins/inputs/snmp/README.md
View File

@ -1,180 +1,221 @@
# SNMP Plugin # SNMP Input Plugin
The SNMP input plugin gathers metrics from SNMP agents. The `snmp` input plugin uses polling to gather metrics from SNMP agents.
Support for gathering individual OIDs as well as complete SNMP tables is
included.
## Configuration: ### Prerequisites
See additional SNMP plugin configuration examples [here](./CONFIG-EXAMPLES.md). This plugin uses the `snmptable` and `snmptranslate` programs from the
[net-snmp][] project. These tools will need to be installed into the `PATH` in
order to be located. Other utilities from the net-snmp project may be useful
for troubleshooting, but are not directly used by the plugin.
### Example: These programs will load available MIBs on the system. Typically the default
directory for MIBs is `/usr/share/snmp/mibs`, but if your MIBs are in a
different location you may need to make the paths known to net-snmp. The
location of these files can be configured in the `snmp.conf` or via the
`MIBDIRS` environment variable. See [`man 1 snmpcmd`][man snmpcmd] for more
information.
SNMP data: ### Configuration
```
.1.0.0.0.1.1.0 octet_str "foo"
.1.0.0.0.1.1.1 octet_str "bar"
.1.0.0.0.1.102 octet_str "bad"
.1.0.0.0.1.2.0 integer 1
.1.0.0.0.1.2.1 integer 2
.1.0.0.0.1.3.0 octet_str "0.123"
.1.0.0.0.1.3.1 octet_str "0.456"
.1.0.0.0.1.3.2 octet_str "9.999"
.1.0.0.1.1 octet_str "baz"
.1.0.0.1.2 uinteger 54321
.1.0.0.1.3 uinteger 234
```
Telegraf config:
```toml ```toml
[[inputs.snmp]] [[inputs.snmp]]
agents = [ "127.0.0.1:161" ] ## Agent addresses to retrieve values from.
version = 2 ## example: agents = ["udp://127.0.0.1:161"]
community = "public" ## agents = ["tcp://127.0.0.1:161"]
agents = ["udp://127.0.0.1:161"]
name = "system" ## Timeout for each request.
[[inputs.snmp.field]] # timeout = "5s"
name = "hostname"
oid = ".1.0.0.1.1" ## SNMP version; can be 1, 2, or 3.
is_tag = true # version = 2
## SNMP community string.
# community = "public"
## Number of retries to attempt.
# retries = 3
## The GETBULK max-repetitions parameter.
# max_repetitions = 10
## SNMPv3 authentication and encryption options.
##
## Security Name.
# sec_name = "myuser"
## Authentication protocol; one of "MD5", "SHA", or "".
# auth_protocol = "MD5"
## Authentication password.
# auth_password = "pass"
## Security Level; one of "noAuthNoPriv", "authNoPriv", or "authPriv".
# sec_level = "authNoPriv"
## Context Name.
# context_name = ""
## Privacy protocol used for encrypted messages; one of "DES", "AES" or "".
# priv_protocol = ""
## Privacy password used for encrypted messages.
# priv_password = ""
## Add fields and tables defining the variables you wish to collect. This
## example collects the system uptime and interface variables. Reference the
## full plugin documentation for configuration details.
[[inputs.snmp.field]] [[inputs.snmp.field]]
oid = "RFC1213-MIB::sysUpTime.0"
name = "uptime" name = "uptime"
oid = ".1.0.0.1.2"
[[inputs.snmp.field]] [[inputs.snmp.field]]
name = "loadavg" oid = "RFC1213-MIB::sysName.0"
oid = ".1.0.0.1.3" name = "source"
conversion = "float(2)" is_tag = true
[[inputs.snmp.table]] [[inputs.snmp.table]]
name = "remote_servers" oid = "IF-MIB::ifTable"
inherit_tags = [ "hostname" ] name = "interface"
inherit_tags = ["source"]
[[inputs.snmp.table.field]] [[inputs.snmp.table.field]]
name = "server" oid = "IF-MIB::ifDescr"
oid = ".1.0.0.0.1.1" name = "ifDescr"
is_tag = true is_tag = true
[[inputs.snmp.table.field]]
name = "connections"
oid = ".1.0.0.0.1.2"
[[inputs.snmp.table.field]]
name = "latency"
oid = ".1.0.0.0.1.3"
conversion = "float"
``` ```
Resulting output: #### Configure SNMP Requests
```
* Plugin: snmp, Collection 1
> system,agent_host=127.0.0.1,host=mylocalhost,hostname=baz loadavg=2.34,uptime=54321i 1468953135000000000
> remote_servers,agent_host=127.0.0.1,host=mylocalhost,hostname=baz,server=foo connections=1i,latency=0.123 1468953135000000000
> remote_servers,agent_host=127.0.0.1,host=mylocalhost,hostname=baz,server=bar connections=2i,latency=0.456 1468953135000000000
```
#### Configuration via MIB: This plugin provides two methods for configuring the SNMP requests: `fields`
and `tables`. Use the `field` option to gather single ad-hoc variables.
To collect SNMP tables, use the `table` option.
This example uses the SNMP data above, but is configured via the MIB. ##### Field
The example MIB file can be found in the `testdata` directory. See the [MIB lookups](#mib-lookups) section for more information.
Use a `field` to collect a variable by OID. Requests specified with this
option operate similar to the `snmpget` utility.
Telegraf config:
```toml ```toml
[[inputs.snmp]] [[inputs.snmp]]
agents = [ "127.0.0.1:161" ] # ... snip ...
version = 2
community = "public"
[[inputs.snmp.field]] [[inputs.snmp.field]]
oid = "TEST::hostname" ## Object identifier of the variable as a numeric or textual OID.
is_tag = true oid = "RFC1213-MIB::sysName.0"
## Name of the field or tag to create. If not specified, it defaults to
## the value of 'oid'. If 'oid' is numeric, an attempt to translate the
## numeric OID into a textual OID will be made.
# name = ""
## If true the variable will be added as a tag, otherwise a field will be
## created.
# is_tag = false
## Apply one of the following conversions to the variable value:
## float(X) Convert the input value into a float and divides by the
## Xth power of 10. Efficively just moves the decimal left
## X places. For example a value of `123` with `float(2)`
## will result in `1.23`.
## float: Convert the value into a float with no adjustment. Same
## as `float(0)`.
## int: Convert the value into an integer.
## hwaddr: Convert the value to a MAC address.
## ipaddr: Convert the value to an IP address.
# conversion = ""
```
##### Table
Use a `table` to configure the collection of a SNMP table. SNMP requests
formed with this option operate similarly way to the `snmptable` command.
Control the handling of specific table columns using a nested `field`. These
nested fields are specified similarly to a top-level `field`.
All columns of the SNMP table will be collected, it is not required to add a
nested field for each column, only those which you wish to modify. To exclude
columns use [metric filtering][].
One [metric][] is created for each row of the SNMP table.
```toml
[[inputs.snmp]]
# ... snip ...
[[inputs.snmp.table]] [[inputs.snmp.table]]
oid = "TEST::testTable" ## Object identifier of the SNMP table as a numeric or textual OID.
inherit_tags = [ "hostname" ] oid = "IF-MIB::ifTable"
## Name of the field or tag to create. If not specified, it defaults to
## the value of 'oid'. If 'oid' is numeric an attempt to translate the
## numeric OID into a textual OID will be made.
# name = ""
## Which tags to inherit from the top-level config and to use in the output
## of this table's measurement.
## example: inherit_tags = ["source"]
# inherit_tags = []
## Add an 'index' tag with the table row number. Use this if the table has
## no indexes or if you are excluding them. This option is normally not
## required as any index columns are automatically added as tags.
# index_as_tag = false
[[inputs.snmp.table.field]]
## OID to get. May be a numeric or textual module-qualified OID.
oid = "IF-MIB::ifDescr"
## Name of the field or tag to create. If not specified, it defaults to
## the value of 'oid'. If 'oid' is numeric an attempt to translate the
## numeric OID into a textual OID will be made.
# name = ""
## Output this field as a tag.
# is_tag = false
## The OID sub-identifier to strip off so that the index can be matched
## against other fields in the table.
# oid_index_suffix = ""
## Specifies the length of the index after the supplied table OID (in OID
## path segments). Truncates the index after this point to remove non-fixed
## value or length index suffixes.
# oid_index_length = 0
``` ```
Resulting output: ### Troubleshooting
Check that a numeric field can be translated to a textual field:
``` ```
* Plugin: snmp, Collection 1 $ snmptranslate .1.3.6.1.2.1.1.3.0
> testTable,agent_host=127.0.0.1,host=mylocalhost,hostname=baz,server=foo connections=1i,latency="0.123" 1468953135000000000 DISMAN-EVENT-MIB::sysUpTimeInstance
> testTable,agent_host=127.0.0.1,host=mylocalhost,hostname=baz,server=bar connections=2i,latency="0.456" 1468953135000000000
``` ```
### Config parameters Request a top-level field:
```
$ snmpget -v2c -c public 127.0.0.1 sysUpTime.0
```
* `agents`: Default: `[]` Request a table:
List of SNMP agents to connect to in the form of `[tcp://]IP[:PORT]`. If `:PORT` is unspecified, it defaults to `161`. When using the optional prefix `tcp://`, SNMP over TCP will be used. Otherwise UDP is used as the transport protocol. ```
$ snmptable -v2c -c public 127.0.0.1 ifTable
```
* `version`: Default: `2` To collect a packet capture, run this command in the background while running
SNMP protocol version to use. Telegraf or one of the above commands. Adjust the interface, host and port as
needed:
```
$ sudo tcpdump -s 0 -i eth0 -w telegraf-snmp.pcap host 127.0.0.1 and port 161
```
* `community`: Default: `"public"` ### Example Output
SNMP community to use.
* `max_repetitions`: Default: `50` ```
Maximum number of iterations for repeating variables. snmp,agent_host=127.0.0.1,source=loaner uptime=11331974i 1575509815000000000
interface,agent_host=127.0.0.1,ifDescr=wlan0,ifIndex=3,source=example.org ifAdminStatus=1i,ifInDiscards=0i,ifInErrors=0i,ifInNUcastPkts=0i,ifInOctets=3436617431i,ifInUcastPkts=2717778i,ifInUnknownProtos=0i,ifLastChange=0i,ifMtu=1500i,ifOperStatus=1i,ifOutDiscards=0i,ifOutErrors=0i,ifOutNUcastPkts=0i,ifOutOctets=581368041i,ifOutQLen=0i,ifOutUcastPkts=1354338i,ifPhysAddress="c8:5b:76:c9:e6:8c",ifSpecific=".0.0",ifSpeed=0i,ifType=6i 1575509815000000000
interface,agent_host=127.0.0.1,ifDescr=eth0,ifIndex=2,source=example.org ifAdminStatus=1i,ifInDiscards=0i,ifInErrors=0i,ifInNUcastPkts=21i,ifInOctets=3852386380i,ifInUcastPkts=3634004i,ifInUnknownProtos=0i,ifLastChange=9088763i,ifMtu=1500i,ifOperStatus=1i,ifOutDiscards=0i,ifOutErrors=0i,ifOutNUcastPkts=0i,ifOutOctets=434865441i,ifOutQLen=0i,ifOutUcastPkts=2110394i,ifPhysAddress="c8:5b:76:c9:e6:8c",ifSpecific=".0.0",ifSpeed=1000000000i,ifType=6i 1575509815000000000
interface,agent_host=127.0.0.1,ifDescr=lo,ifIndex=1,source=example.org ifAdminStatus=1i,ifInDiscards=0i,ifInErrors=0i,ifInNUcastPkts=0i,ifInOctets=51555569i,ifInUcastPkts=339097i,ifInUnknownProtos=0i,ifLastChange=0i,ifMtu=65536i,ifOperStatus=1i,ifOutDiscards=0i,ifOutErrors=0i,ifOutNUcastPkts=0i,ifOutOctets=51555569i,ifOutQLen=0i,ifOutUcastPkts=339097i,ifSpecific=".0.0",ifSpeed=10000000i,ifType=24i 1575509815000000000
```
* `sec_name`: [net-snmp]: http://www.net-snmp.org/
Security name for authenticated SNMPv3 requests. [man snmpcmd]: http://net-snmp.sourceforge.net/docs/man/snmpcmd.html#lbAK
[metric filtering]: /docs/CONFIGURATION.md#metric-filtering
* `auth_protocol`: Values: `"MD5"`,`"SHA"`,`""`. Default: `""` [metric]: /docs/METRICS.md
Authentication protocol for authenticated SNMPv3 requests.
* `auth_password`:
Authentication password for authenticated SNMPv3 requests.
* `sec_level`: Values: `"noAuthNoPriv"`,`"authNoPriv"`,`"authPriv"`. Default: `"noAuthNoPriv"`
Security level used for SNMPv3 messages.
* `context_name`:
Context name used for SNMPv3 requests.
* `priv_protocol`: Values: `"DES"`,`"AES"`,`""`. Default: `""`
Privacy protocol used for encrypted SNMPv3 messages.
* `priv_password`:
Privacy password used for encrypted SNMPv3 messages.
* `name`:
Output measurement name.
#### Field parameters:
* `oid`:
OID to get. May be a numeric or textual OID.
* `oid_index_suffix`:
The OID sub-identifier to strip off so that the index can be matched against other fields in the table.
* `oid_index_length`:
Specifies the length of the index after the supplied table OID (in OID path segments). Truncates the index after this point to remove non-fixed value or length index suffixes.
* `name`:
Output field/tag name.
If not specified, it defaults to the value of `oid`. If `oid` is numeric, an attempt to translate the numeric OID into a texual OID will be made.
* `is_tag`:
Output this field as a tag.
* `conversion`: Values: `"float(X)"`,`"float"`,`"int"`,`""`. Default: `""`
Converts the value according to the given specification.
- `float(X)`: Converts the input value into a float and divides by the Xth power of 10. Efficively just moves the decimal left X places. For example a value of `123` with `float(2)` will result in `1.23`.
- `float`: Converts the value into a float with no adjustment. Same as `float(0)`.
- `int`: Convertes the value into an integer.
- `hwaddr`: Converts the value to a MAC address.
- `ipaddr`: Converts the value to an IP address.
#### Table parameters:
* `oid`:
Automatically populates the table's fields using data from the MIB.
* `name`:
Output measurement name.
If not specified, it defaults to the value of `oid`. If `oid` is numeric, an attempt to translate the numeric OID into a texual OID will be made.
* `inherit_tags`:
Which tags to inherit from the top-level config and to use in the output of this table's measurement.
* `index_as_tag`:
Adds each row's index within the table as a tag.
### MIB lookups
If the plugin is configured such that it needs to perform lookups from the MIB, it will use the net-snmp utilities `snmptranslate` and `snmptable`.
When performing the lookups, the plugin will load all available MIBs. If your MIB files are in a custom path, you may add the path using the `MIBDIRS` environment variable. See [`man 1 snmpcmd`](http://net-snmp.sourceforge.net/docs/man/snmpcmd.html#lbAK) for more information on the variable.

120
plugins/inputs/snmp/snmp.go
View File

@ -22,61 +22,46 @@ import (
const description = `Retrieves SNMP values from remote agents` const description = `Retrieves SNMP values from remote agents`
const sampleConfig = ` const sampleConfig = `
agents = [ "127.0.0.1:161" ] ## Agent addresses to retrieve values from.
## Timeout for each SNMP query. ## example: agents = ["udp://127.0.0.1:161"]
timeout = "5s" ## agents = ["tcp://127.0.0.1:161"]
## Number of retries to attempt within timeout. agents = ["udp://127.0.0.1:161"]
retries = 3
## SNMP version, values can be 1, 2, or 3 ## Timeout for each request.
version = 2 # timeout = "5s"
## SNMP version; can be 1, 2, or 3.
# version = 2
## SNMP community string. ## SNMP community string.
community = "public" # community = "public"
## The GETBULK max-repetitions parameter ## Number of retries to attempt.
max_repetitions = 10 # retries = 3
## SNMPv3 auth parameters ## The GETBULK max-repetitions parameter.
#sec_name = "myuser" # max_repetitions = 10
#auth_protocol = "md5" # Values: "MD5", "SHA", ""
#auth_password = "pass"
#sec_level = "authNoPriv" # Values: "noAuthNoPriv", "authNoPriv", "authPriv"
#context_name = ""
#priv_protocol = "" # Values: "DES", "AES", ""
#priv_password = ""
## measurement name ## SNMPv3 authentication and encryption options.
name = "system" ##
[[inputs.snmp.field]] ## Security Name.
name = "hostname" # sec_name = "myuser"
oid = ".1.0.0.1.1" ## Authentication protocol; one of "MD5", "SHA", or "".
[[inputs.snmp.field]] # auth_protocol = "MD5"
name = "uptime" ## Authentication password.
oid = ".1.0.0.1.2" # auth_password = "pass"
[[inputs.snmp.field]] ## Security Level; one of "noAuthNoPriv", "authNoPriv", or "authPriv".
name = "load" # sec_level = "authNoPriv"
oid = ".1.0.0.1.3" ## Context Name.
[[inputs.snmp.field]] # context_name = ""
oid = "HOST-RESOURCES-MIB::hrMemorySize" ## Privacy protocol used for encrypted messages; one of "DES", "AES" or "".
# priv_protocol = ""
## Privacy password used for encrypted messages.
# priv_password = ""
[[inputs.snmp.table]] ## Add fields and tables defining the variables you wish to collect. This
## measurement name ## example collects the system uptime and interface variables. Reference the
name = "remote_servers" ## full plugin documentation for configuration details.
inherit_tags = [ "hostname" ]
[[inputs.snmp.table.field]]
name = "server"
oid = ".1.0.0.0.1.0"
is_tag = true
[[inputs.snmp.table.field]]
name = "connections"
oid = ".1.0.0.0.1.1"
[[inputs.snmp.table.field]]
name = "latency"
oid = ".1.0.0.0.1.2"
[[inputs.snmp.table]]
## auto populate table's fields using the MIB
oid = "HOST-RESOURCES-MIB::hrNetworkTable"
` `
// execCommand is so tests can mock out exec.Command usage. // execCommand is so tests can mock out exec.Command usage.
@ -108,41 +93,42 @@ func execCmd(arg0 string, args ...string) ([]byte, error) {
// Snmp holds the configuration for the plugin. // Snmp holds the configuration for the plugin.
type Snmp struct { type Snmp struct {
// The SNMP agent to query. Format is ADDR[:PORT] (e.g. 1.2.3.4:161). // The SNMP agent to query. Format is [SCHEME://]ADDR[:PORT] (e.g.
Agents []string // udp://1.2.3.4:161). If the scheme is not specified then "udp" is used.
Agents []string `toml:"agents"`
// Timeout to wait for a response. // Timeout to wait for a response.
Timeout internal.Duration Timeout internal.Duration `toml:"timeout"`
Retries int Retries int `toml:"retries"`
// Values: 1, 2, 3 // Values: 1, 2, 3
Version uint8 Version uint8 `toml:"version"`
// Parameters for Version 1 & 2 // Parameters for Version 1 & 2
Community string Community string `toml:"community"`
// Parameters for Version 2 & 3 // Parameters for Version 2 & 3
MaxRepetitions uint8 MaxRepetitions uint8 `toml:"max_repetitions"`
// Parameters for Version 3 // Parameters for Version 3
ContextName string ContextName string `toml:"context_name"`
// Values: "noAuthNoPriv", "authNoPriv", "authPriv" // Values: "noAuthNoPriv", "authNoPriv", "authPriv"
SecLevel string SecLevel string `toml:"sec_level"`
SecName string SecName string `toml:"sec_name"`
// Values: "MD5", "SHA", "". Default: "" // Values: "MD5", "SHA", "". Default: ""
AuthProtocol string AuthProtocol string `toml:"auth_protocol"`
AuthPassword string AuthPassword string `toml:"auth_password"`
// Values: "DES", "AES", "". Default: "" // Values: "DES", "AES", "". Default: ""
PrivProtocol string PrivProtocol string `toml:"priv_protocol"`
PrivPassword string PrivPassword string `toml:"priv_password"`
EngineID string EngineID string `toml:"-"`
EngineBoots uint32 EngineBoots uint32 `toml:"-"`
EngineTime uint32 EngineTime uint32 `toml:"-"`
Tables []Table `toml:"table"` Tables []Table `toml:"table"`
// Name & Fields are the elements of a Table. // Name & Fields are the elements of a Table.
// Telegraf chokes if we try to embed a Table. So instead we have to embed the // Telegraf chokes if we try to embed a Table. So instead we have to embed the
// fields of a Table, and construct a Table during runtime. // fields of a Table, and construct a Table during runtime.
Name string Name string // deprecated in 1.14; use name_override
Fields []Field `toml:"field"` Fields []Field `toml:"field"`
connectionCache []snmpConnection connectionCache []snmpConnection

40
plugins/inputs/snmp/snmp_test.go
View File

@ -10,6 +10,7 @@ import (
"time" "time"
"github.com/influxdata/telegraf/internal" "github.com/influxdata/telegraf/internal"
"github.com/influxdata/telegraf/plugins/inputs"
"github.com/influxdata/telegraf/testutil" "github.com/influxdata/telegraf/testutil"
"github.com/influxdata/toml" "github.com/influxdata/toml"
"github.com/soniah/gosnmp" "github.com/soniah/gosnmp"
@ -82,45 +83,20 @@ var tsc = &testSNMPConnection{
} }
func TestSampleConfig(t *testing.T) { func TestSampleConfig(t *testing.T) {
conf := struct { conf := inputs.Inputs["snmp"]()
Inputs struct { err := toml.Unmarshal([]byte(conf.SampleConfig()), conf)
Snmp []*Snmp require.NoError(t, err)
}
}{}
err := toml.Unmarshal([]byte("[[inputs.snmp]]\n"+(*Snmp)(nil).SampleConfig()), &conf)
assert.NoError(t, err)
s := Snmp{ expected := &Snmp{
Agents: []string{"127.0.0.1:161"}, Agents: []string{"udp://127.0.0.1:161"},
Timeout: internal.Duration{Duration: 5 * time.Second}, Timeout: internal.Duration{Duration: 5 * time.Second},
Version: 2, Version: 2,
Community: "public", Community: "public",
MaxRepetitions: 10, MaxRepetitions: 10,
Retries: 3, Retries: 3,
Name: "snmp",
Name: "system",
Fields: []Field{
{Name: "hostname", Oid: ".1.0.0.1.1"},
{Name: "uptime", Oid: ".1.0.0.1.2"},
{Name: "load", Oid: ".1.0.0.1.3"},
{Oid: "HOST-RESOURCES-MIB::hrMemorySize"},
},
Tables: []Table{
{
Name: "remote_servers",
InheritTags: []string{"hostname"},
Fields: []Field{
{Name: "server", Oid: ".1.0.0.0.1.0", IsTag: true},
{Name: "connections", Oid: ".1.0.0.0.1.1"},
{Name: "latency", Oid: ".1.0.0.0.1.2"},
},
},
{
Oid: "HOST-RESOURCES-MIB::hrNetworkTable",
},
},
} }
assert.Equal(t, &s, conf.Inputs.Snmp[0]) require.Equal(t, expected, conf)
} }
func TestFieldInit(t *testing.T) { func TestFieldInit(t *testing.T) {

62
plugins/inputs/snmp_trap/README.md
View File

@ -6,13 +6,22 @@ notifications (traps and inform requests).
Notifications are received on plain UDP. The port to listen is Notifications are received on plain UDP. The port to listen is
configurable. configurable.
OIDs can be resolved to strings using system MIB files. This is done ### Prerequisites
in same way as the SNMP input plugin. See the section "MIB Lookups" in
the SNMP [README.md](../snmp/README.md) for details. This plugin uses the `snmptranslate` programs from the
[net-snmp][] project. These tools will need to be installed into the `PATH` in
order to be located. Other utilities from the net-snmp project may be useful
for troubleshooting, but are not directly used by the plugin.
These programs will load available MIBs on the system. Typically the default
directory for MIBs is `/usr/share/snmp/mibs`, but if your MIBs are in a
different location you may need to make the paths known to net-snmp. The
location of these files can be configured in the `snmp.conf` or via the
`MIBDIRS` environment variable. See [`man 1 snmpcmd`][man snmpcmd] for more
information.
### Configuration ### Configuration
```toml ```toml
# Snmp trap listener
[[inputs.snmp_trap]] [[inputs.snmp_trap]]
## Transport, local address, and port to listen on. Transport must ## Transport, local address, and port to listen on. Transport must
## be "udp://". Omit local address to listen on all interfaces. ## be "udp://". Omit local address to listen on all interfaces.
@ -26,27 +35,7 @@ the SNMP [README.md](../snmp/README.md) for details.
# timeout = "5s" # timeout = "5s"
``` ```
### Metrics #### Using a Privileged Port
- snmp_trap
- tags:
- source (string, IP address of trap source)
- name (string, value from SNMPv2-MIB::snmpTrapOID.0 PDU)
- mib (string, MIB from SNMPv2-MIB::snmpTrapOID.0 PDU)
- oid (string, OID string from SNMPv2-MIB::snmpTrapOID.0 PDU)
- version (string, "1" or "2c" or "3")
- fields:
- Fields are mapped from variables in the trap. Field names are
the trap variable names after MIB lookup. Field values are trap
variable values.
### Example Output
```
snmp_trap,mib=SNMPv2-MIB,name=coldStart,oid=.1.3.6.1.6.3.1.1.5.1,source=192.168.122.102,version=2c snmpTrapEnterprise.0="linux",sysUpTimeInstance=1i 1574109187723429814
snmp_trap,mib=NET-SNMP-AGENT-MIB,name=nsNotifyShutdown,oid=.1.3.6.1.4.1.8072.4.0.2,source=192.168.122.102,version=2c sysUpTimeInstance=5803i,snmpTrapEnterprise.0="netSnmpNotificationPrefix" 1574109186555115459
```
### Using a Privileged Port
On many operating systems, listening on a privileged port (a port On many operating systems, listening on a privileged port (a port
number less than 1024) requires extra permission. Since the default number less than 1024) requires extra permission. Since the default
@ -70,3 +59,26 @@ setcap cap_net_bind_service=+ep /usr/bin/telegraf
On Mac OS, listening on privileged ports is unrestricted on versions On Mac OS, listening on privileged ports is unrestricted on versions
10.14 and later. 10.14 and later.
### Metrics
- snmp_trap
- tags:
- source (string, IP address of trap source)
- name (string, value from SNMPv2-MIB::snmpTrapOID.0 PDU)
- mib (string, MIB from SNMPv2-MIB::snmpTrapOID.0 PDU)
- oid (string, OID string from SNMPv2-MIB::snmpTrapOID.0 PDU)
- version (string, "1" or "2c" or "3")
- fields:
- Fields are mapped from variables in the trap. Field names are
the trap variable names after MIB lookup. Field values are trap
variable values.
### Example Output
```
snmp_trap,mib=SNMPv2-MIB,name=coldStart,oid=.1.3.6.1.6.3.1.1.5.1,source=192.168.122.102,version=2c snmpTrapEnterprise.0="linux",sysUpTimeInstance=1i 1574109187723429814
snmp_trap,mib=NET-SNMP-AGENT-MIB,name=nsNotifyShutdown,oid=.1.3.6.1.4.1.8072.4.0.2,source=192.168.122.102,version=2c sysUpTimeInstance=5803i,snmpTrapEnterprise.0="netSnmpNotificationPrefix" 1574109186555115459
```
[net-snmp]: http://www.net-snmp.org/
[man snmpcmd]: http://net-snmp.sourceforge.net/docs/man/snmpcmd.html#lbAK