SNMP¶

This article focuses on SNMP data collection.

Terminology¶

• SNMP (Simple network management protocol): A network protocol that is used to collect information about bare metal networking gear.
• OID (Object identifier): A unique ID or address on a device that when polled returns the response code of that value. For example, OIDs are CPU or device fan speed.
• sysOID (System object identifier): A specific address that defines the device type. All devices have a unique ID that defines it. For example, the Meraki base sysOID is 1.3.6.1.4.1.29671.
• MIB (Managed information base): A database or list of all the possible OIDs and their definitions that are related to the MIB. For example, the IF-MIB (interface MIB) contains all the OIDs for descriptive information about a device’s interface.

About SNMP Protocol¶

The SNMP protocol is divided into three versions: v1/v2c/v3, of which:

• V1 and v2c are compatible. Many SNMP devices only offer v2c and v3 versions. v2c version, the best compatibility, many older devices only support this version.
• If the safety requirements are high, choose v3. Security is also the main difference between v3 version and previous versions.

Datakit supports all of the above versions.

Choosing v1/v2c version¶

If you choose v1/v2c version, you need to provide community string, AKA community name/community string/unencrypted password, which is required for authentication when interacting with an SNMP device. In addition, some devices will be distinguished into read-only community name and read-write community name. As the name implies:

• Read-only community name: The device will only provide internal metrics data to that party, and cannot modify some internal configurations (this is enough for DataKit).
• Read-write community name: The provider has the permission to query the internal metrics data of the equipment and modify some configurations.

Choosing v3 version¶

If you choose v3 version, you need to provide username, authentication algorithm/password, encryption algorithm/password, context, etc. Each device is different and should be filled in as same as configuration in SNMP device.

Configuration¶

Input Configuration¶

[[inputs.snmp]]
  ## Filling in specific device IP address, like ["10.200.10.240", "10.200.10.241"].
  ## And you can use auto_discovery and specific_devices at the same time.
  ## If you don't want to specific device, you don't need provide this.
  #
  # specific_devices = ["***"] # SNMP Device IP.

  ## Filling in autodiscovery CIDR subnet, like ["10.200.10.0/24", "10.200.20.0/24"].
  ## If you don't want to enable autodiscovery feature, you don't need provide this.
  #
  # auto_discovery = ["***"] # Used in autodiscovery mode only, ignore this in other cases.

  ## SNMP protocol version the devices using, fill in 2 or 3.
  ## If you using the version 1, just fill in 2. Version 2 supported version 1.
  ## This is must be provided.
  #
  snmp_version = 2

  ## SNMP port in the devices. Default is 161. In most cases, you don't need change this.
  ## This is optional.
  #
  # port = 161

  ## Password in SNMP v2, enclose with single quote. Only worked in SNMP v2.
  ## If you are using SNMP v2, this is must be provided.
  ## If you are using SNMP v3, you don't need provide this.
  #
  # v2_community_string = "***"

  ## Authentication stuff in SNMP v3.
  ## If you are using SNMP v2, you don't need provide this.
  ## If you are using SNMP v3, this is must be provided.
  #
  # v3_user = "***"
  # v3_auth_protocol = "***"
  # v3_auth_key = "***"
  # v3_priv_protocol = "***"
  # v3_priv_key = "***"
  # v3_context_engine_id = "***"
  # v3_context_name = "***"

  ## Number of workers used to collect and discovery devices concurrently. Default is 100.
  ## Modifying it based on device's number and network scale.
  ## This is optional.
  #
  # workers = 100

  ## Interval between each autodiscovery in seconds. Default is "1h".
  ## Only worked in autodiscovery feature.
  ## This is optional.
  #
  # discovery_interval = "1h"

  ## Filling in excluded device IP address, like ["10.200.10.220", "10.200.10.221"].
  ## Only worked in autodiscovery feature.
  ## This is optional.
  #
  # discovery_ignored_ip = []

  ## Set true to enable election
  #
  # election = true

  ## Device Namespace. Default is "default".
  #
  # device_namespace = "default"

  ## Picking the metric data only contains the field's names below.
  #
  # enable_picking_data = true # Default is "false", which means collecting all data.
  # status = ["sysUpTimeInstance", "tcpCurrEstab", "ifAdminStatus", "ifOperStatus", "cswSwitchState"]
  # speed = ["ifHCInOctets", "ifHCInOctetsRate", "ifHCOutOctets", "ifHCOutOctetsRate", "ifHighSpeed", "ifSpeed", "ifBandwidthInUsageRate", "ifBandwidthOutUsageRate"]
  # cpu = ["cpuUsage"]
  # mem = ["memoryUsed", "memoryUsage", "memoryFree"]
  # extra = []

  [inputs.snmp.tags]
  # tag1 = "val1"
  # tag2 = "val2"

  [inputs.snmp.traps]
  # enable = true
  # bind_host = "0.0.0.0"
  # port = 9162
  # stop_timeout = 3    # stop timeout in seconds.

sudo datakit debug --input-conf /usr/local/datakit/conf.d/snmp/snmp.conf

Configure SNMP¶

• On the device side, configure the SNMP protocol

When SNMP devices are in the default, the general SNMP protocol is closed, you need to enter the management interface to open manually. At the same time, it is necessary to select the protocol version and fill in the corresponding information according to the actual situation.

# Applicable v2c version
snmpwalk -O bentU -v 2c -c [community string] [SNMP_DEVICE_IP] 1.3.6
# Applicable v3 version
snmpwalk -v 3 -u user -l authPriv -a sha -A [AUTH_PASSWORD] -x aes -X [ENCRYPT_PASSWORD] [SNMP_DEVICE_IP] 1.3.6

sudo yum install net-snmp net-snmp-utils # CentOS
sudo apt–get install snmp                # Ubuntu

• On the DataKit side, configure collection.

Advanced features¶

Custom Device OID configuration¶

If you find that the data reported by the collected device does not contain the indicators you want, then you may need to define an additional Profile for the device.

All OIDs of devices can generally be downloaded from their official website. Datakit defines some common OIDs, as well as some devices such as Cisco/Dell/HP. According to SNMP protocol, each device manufacturer can customize OID to identify its internal special objects. If you want to identify these, you need to customize the configuration of the device (we call this configuration Profile here, that is, "Custom Profile"), as follows.

To add metrics or a custom configuration, list the MIB name, table name, table OID, symbol, and symbol OID, for example:

- MIB: EXAMPLE-MIB
    table:
      # Identification of the table which metrics come from.
      OID: 1.3.6.1.4.1.10
      name: exampleTable
    symbols:
      # List of symbols ('columns') to retrieve.
      # Same format as for a single OID.
      # Each row in the table emits these metrics.
      - OID: 1.3.6.1.4.1.10.1.1
        name: exampleColumn1

Here is an example of operation.

Create the yml file cisco-3850.yaml under the path conf.d/snmp/profiles of the Datakit installation directory (in this case, Cisco 3850) as follows:

# Backward compatibility shim. Prefer the Cisco Catalyst profile directly
# Profile for Cisco 3850 devices

extends:
  - _base.yaml
  - _cisco-generic.yaml
  - _cisco-catalyst.yaml

sysobjectid: 1.3.6.1.4.1.9.1.1745 # cat38xxstack

device:
  vendor: "cisco"

# Example sysDescr:
#   Cisco IOS Software, IOS-XE Software, Catalyst L3 Switch Software (CAT3K_CAA-UNIVERSALK9-M), Version 03.06.06E RELEASE SOFTWARE (fc1) Technical Support: http://www.cisco.com/techsupport Copyright (c) 1986-2016 by Cisco Systems, Inc. Compiled Sat 17-Dec-

metadata:
  device:
    fields:
      serial_number:
        symbol:
          MIB: OLD-CISCO-CHASSIS-MIB
          OID: 1.3.6.1.4.1.9.3.6.3.0
          name: info

metrics:
  # iLO controller metrics.

  - # Power state.
    # NOTE: unknown(1), poweredOff(2), poweredOn(3), insufficientPowerOrPowerOnDenied(4)
    MIB: CPQSM2-MIB
    symbol:
      OID: 1.3.6.1.4.1.232.9.2.2.32
      name: temperature

As shown above, a device with sysobjectid of 1.3.6.1.4.1.9.1.1745 is defined, and the next time Datakit captures a device with the same sysobjectid, the file will be applied, in this case:

• When device data is captured for an OID of 1.3.6.1.4.1.9.3.6.3.0, the field with the name serial_number will added to the device_meta field(JSON), and appended to the set snmp_object to be reported as an Object;
• When device data is captured for an OID of 1.3.6.1.4.1.232.9.2.2.32, the field with the name temperature will added to the the metric set snmp_metric and reported as a Metric;

Metric¶

All of the following data collections are appended by default with the name host (the value is the name of the SNMP device), or other labels can be specified in the configuration by [inputs.snmp.tags]:

 [inputs.snmp.tags]
  # some_tag = "some_value"
  # more_tag = "some_other_value"
  # ...

snmp_metric¶

SNMP device metric data.

• tag

• field list

Object¶

snmp_object¶

SNMP device object data.

• tag

• field list

FAQ¶

How dows Datakit find devices?¶

Datakit supports "Specified device mode" and "auto-discovery mode" two modes. The two modes can enabled at the same time.

In "specified device mode", Datakit communicates with the specified IP device using the SNMP protocol to know its current online status.

In "auto-discovery mode", Datakit sends SNMP packets to all address in the specified IP segment one by one, and if the response matches the corresponding profile, Datakit assumes that there is a SNMP device on that IP.

I can't find metrics I'm looking for in Guance, what should I do?¶

Datakit collects generic base-line metrics from all devices. If you can't find the metric you want, you can write a custom profile.

To archiving this, you probably needs to download the device's OID manual from its official website.

Why I can't see any metrics in Guance after I completed configuration?¶

Try loosening ACLs/firewall rules for your devices.

Run snmpwalk -O bentU -v 2c -c <COMMUNITY_STRING> <IP_ADDRESS>:<PORT> 1.3.6 from the host Datakit is running on. If you get a timeout without any response, there is likely something blocking Datakit from collecting metrics from your device.