ContextQMD
Back to Telegraf

SNMP Trap Input Plugin

plugins/inputs/snmp_trap/README.md

1.38.35.4 KB
Original Source

SNMP Trap Input Plugin

This service plugin listens for SNMP notifications like traps and inform requests. Notifications are received on plain UDP with a configurable port.

[!NOTE] The path setting is shared between all instances of all SNMP plugin types!

⭐ Telegraf v1.13.0 🏷️ hardware, network 💻 all

Service Input <!-- @/docs/includes/service_input.md -->

This plugin is a service input. Normal plugins gather metrics determined by the interval setting. Service plugins start a service to listen and wait for metrics or events to occur. Service plugins have two key differences from normal plugins:

  1. The global or plugin specific interval setting may not apply
  2. The CLI options of --test, --test-wait, and --once may not produce output for this plugin

Global configuration options <!-- @/docs/includes/plugin_config.md -->

Plugins support additional global and plugin configuration settings for tasks such as modifying metrics, tags, and fields, creating aliases, and configuring plugin ordering. See CONFIGURATION.md for more details.

Secret-store support

This plugin supports secrets from secret-stores for the sec_name, auth_password and priv_password option. See the secret-store documentation for more details on how to use them.

Configuration

toml
# Receive SNMP traps
[[inputs.snmp_trap]]
  ## Transport, local address, and port to listen on.  Transport must
  ## be "udp://".  Omit local address to listen on all interfaces.
  ##   example: "udp://127.0.0.1:1234"
  ##
  ## Special permissions may be required to listen on a port less than
  ## 1024.  See README.md for details
  ##
  # service_address = "udp://:162"
  ##
  ## Path to mib files
  ## Used by the gosmi translator.
  ## To add paths when translating with netsnmp, use the MIBDIRS environment variable
  # path = ["/usr/share/snmp/mibs"]
  ##
  ## Timeout running snmptranslate command
  ## Used by the netsnmp translator only
  # timeout = "5s"
  ## Snmp version; one of "1", "2c" or "3".
  # version = "2c"
  ## SNMPv3 authentication and encryption options.
  ##
  ## Security Name.
  # sec_name = "myuser"
  ## Authentication protocol; one of "MD5", "SHA", "SHA224", "SHA256", "SHA384", "SHA512" or "".
  # auth_protocol = "MD5"
  ## Authentication password.
  # auth_password = "pass"
  ## Security Level; one of "noAuthNoPriv", "authNoPriv", or "authPriv".
  # sec_level = "authNoPriv"
  ## Privacy protocol used for encrypted messages; one of "DES", "AES", "AES192", "AES192C", "AES256", "AES256C" or "".
  # priv_protocol = ""
  ## Privacy password used for encrypted messages.
  # priv_password = ""

SNMP backend: gosmi vs netsnmp

This plugin supports two backends to translate SNMP objects. By default, Telegraf will use netsnmp, however, this option is deprecated and it is encouraged to migrate to gosmi. If users find issues with gosmi that do not occur with netsnmp please open a project issue on GitHub.

The SNMP backend setting is a global-level setting that applies to all use of SNMP in Telegraf. Users can set this option in the [agent] configuration via the snmp_translator option. See the agent configuration for more details.

Using a Privileged Port

On many operating systems, listening on a privileged port (a port number less than 1024) requires extra permission. Since the default SNMP trap port 162 is in this category, using telegraf to receive SNMP traps may need extra permission.

Instructions for listening on a privileged port vary by operating system. It is not recommended to run telegraf as superuser in order to use a privileged port. Instead follow the principle of least privilege and use a more specific operating system mechanism to allow telegraf to use the port. You may also be able to have telegraf use an unprivileged port and then configure a firewall port forward rule from the privileged port.

To use a privileged port on Linux, you can use setcap to enable the CAP_NET_BIND_SERVICE capability on the telegraf binary:

shell
setcap cap_net_bind_service=+ep /usr/bin/telegraf

On Mac OS, listening on privileged ports is unrestricted on versions 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")
      • context_name (string, value from v3 trap)
      • engine_id (string, value from v3 trap)
      • community (string, value from 1 or 2c trap)
    • 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

text
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,community=public 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,community=public sysUpTimeInstance=5803i,snmpTrapEnterprise.0="netSnmpNotificationPrefix" 1574109186555115459