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¶

When selecting the v1/v2c version, a v2_community_string must be provided for authentication when interacting with SNMP devices. Additionally, some devices further subdivide this into read-only community strings and read-write community strings. As the names suggest:

• 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 v3_user/v3_auth_protocol/v3_auth_key/v3_priv_protocol/v3_priv_key, etc. Each device is different and should be configured as same as configuration in SNMP device.

Configuration¶

Input Configuration¶

[[inputs.snmp]]
  ## Filling in specific device IP address, example ["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, example ["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.

  ## Consul server url for consul discovery
  ## We can discovery snmp instance from consul services
  # consul_discovery_url = "http://127.0.0.1:8500"

  ## Consul token, optional.
  # consul_token = "<consul token>"

  ## Instance ip key name. ("IP" case sensitive)
  # instance_ip_key = "IP"

  ## Witch task will collect, according to consul service filed "Address"
  ## [] mean collect all, optional, default to []
  # exporter_ips = ["<ip1>", "<ip2>"...]

  ## Consul TLS connection config, optional.
  # ca_certs = ["/opt/tls/ca.crt"]
  # cert = "/opt/tls/client.crt"
  # cert_key = "/opt/tls/client.key"
  # insecure_skip_verify = true

  ## 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 for 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 = "" # MD5/SHA/SHA224/SHA256/SHA384/SHA512 or empty
  # v3_auth_key = ""
  # v3_priv_protocol = "" # DES/AES/AES192/AES192C/AES256/AES256C or empty
  # v3_priv_key = ""
  # v3_context_engine_id = "" # optional
  # v3_context_name = ""      # optional

  ## 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

  ## Number of max OIDs during walk(default 1000)
  # max_oids = 1000

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

  ## Collect metric interval, default is 10s. (optional)
  # metric_interval = "10s"

  ## Collect object interval, default is 5m. (optional)
  # object_interval = "5m"

  ## Filling in excluded device IP address, example ["10.200.10.220", "10.200.10.221"].
  ## Only worked in auto discovery 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 = []

  ## The matched tags would be dropped.
  # tags_ignore = ["Key1","key2"]

  ## The regexp matched tags would be dropped.
  # tags_ignore_regexp = ["^key1$","^(a|bc|de)$"]

  ## Zabbix profiles
  # [[inputs.snmp.zabbix_profiles]]
    ## Can be full path file name or only file name.
    ## If only file name, the path is "./conf.d/snmp/userprofiles/
    ## Suffix can be .yaml .yml .xml
    # profile_name = "xxx.yaml"
    ## ip_list is optional
    # ip_list = ["ip1", "ip2"]
    ## Device class, Best to use the following words:
    ## access_point, firewall, load_balancer, pdu, printer, router, sd_wan, sensor, server, storage, switch, ups, wlc, net_device
    # class = "server"

  # [[inputs.snmp.zabbix_profiles]]
    # profile_name = "yyy.xml"
    # ip_list = ["ip3", "ip4"]
    # class = "switch"

  # ...

  ## Prometheus snmp_exporter profiles, 
  ## If module mapping different class, can disassemble yml file.
  # [[inputs.snmp.prom_profiles]]
    # profile_name = "xxx.yml"
    ## ip_list useful when xxx.yml have 1 module 
    # ip_list = ["ip1", "ip2"]
    # class = "net_device"

  # ...

  ## Prometheus consul discovery module mapping.  ("type"/"isp" case sensitive)
  # [[inputs.snmp.module_regexps]]
    # module = "vpn5"
    ## There is an and relationship between step regularization
    # step_regexps = [["type", "vpn"],["isp", "CT"]]

  # [[inputs.snmp.module_regexps]]
    # module = "switch"
    # step_regexps = [["type", "switch"]]

  # ...

  ## Field key or tag key mapping. Do NOT edit.
  [inputs.snmp.key_mapping]
    CNTLR_NAME = "unit_name"
    DISK_NAME = "unit_name"
    ENT_CLASS = "unit_class"
    ENT_NAME = "unit_name"
    FAN_DESCR = "unit_desc"
    IF_OPERS_TATUS = "unit_status"
    IFADMINSTATUS = "unit_status"
    IFALIAS = "unit_alias"
    IFDESCR = "unit_desc"
    IFNAME = "unit_name"
    IFOPERSTATUS = "unit_status"
    IFTYPE = "unit_type"
    PSU_DESCR = "unit_desc"
    SENSOR_LOCALE = "unit_locale"
    SNMPINDEX = "snmp_index"
    SNMPVALUE = "snmp_value"
    TYPE = "unit_type"
    SENSOR_INFO = "unit_desc"
    ## We can add more mapping below
    # dev_fan_speed = "fanSpeed"
    # dev_disk_size = "diskTotal

  ## Reserved oid-key mappings. Do NOT edit.
  [inputs.snmp.oid_keys]
    "1.3.6.1.2.1.1.3.0" = "netUptime"
    "1.3.6.1.2.1.25.1.1.0" = "uptime"
    "1.3.6.1.2.1.2.2.1.13" = "ifInDiscards"
    "1.3.6.1.2.1.2.2.1.14" = "ifInErrors"
    "1.3.6.1.2.1.31.1.1.1.6" = "ifHCInOctets"
    "1.3.6.1.2.1.2.2.1.19" = "ifOutDiscards"
    "1.3.6.1.2.1.2.2.1.20" = "ifOutErrors"
    "1.3.6.1.2.1.31.1.1.1.10" = "ifHCOutOctets"
    "1.3.6.1.2.1.31.1.1.1.15" = "ifHighSpeed"
    "1.3.6.1.2.1.2.2.1.8" = "ifNetStatus"
    ## We can add more oid-key mapping below

  # [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

Multiple configuration formats¶

Zabbix format¶

• Config

  [[inputs.snmp.zabbix_profiles]]
    profile_name = "xxx.yaml"
    ip_list = ["ip1", "ip2"]
    class = "server"

  [[inputs.snmp.zabbix_profiles]]
    profile_name = "yyy.xml"
    ip_list = ["ip3", "ip4"]
    class = "switch"

  # ...

profile_name can be full path file name or only file name. If only file name, the path is ./conf.d/snmp/userprofiles/

profile_name can from Zabbix official, or from community .

You can modify the yaml or xml.

• AutoDiscovery

  • Automatic discovery matches the collection rules in the imported multiple yaml configurations and performs collection.

  • Please try to configure according to class C. Configuring class B may be slower.

  • If automatic discovery fails to match yaml, it is because these yaml does not contain the manufacturer's signature code of the collected device.

    • Add an oid message to the items of yaml to guide the automatic matching process.

    zabbix_export:
      templates:
      - items:
        - snmp_oid: 1.3.6.1.4.1.2011.5.2.1.1.1.1.6.114.97.100.105.117.115.0.0.0.0
    

    • The oid to be added is obtained by executing the following command. .0.0.0.0 is added at the end to prevent the generation of useless indicators.

    $ snmpwalk -v 2c -c public <ip> 1.3.6.1.2.1.1.2.0
    iso.3.6.1.2.1.1.2.0 = OID: iso.3.6.1.4.1.2011.2.240.12
    
    $ snmpgetnext -v 2c -c public <ip> 1.3.6.1.4.1.2011.2.240.12
    iso.3.6.1.4.1.2011.5.2.1.1.1.1.6.114.97.100.105.117.115 = STRING: "radius"
    

Prometheus format¶

• Config

    [[inputs.snmp.prom_profiles]]
      profile_name = "xxx.yml"
      ip_list = ["ip1", "ip2"]
      class = "server"
  
    [[inputs.snmp.prom_profiles]]
      profile_name = "yyy.yml"
      ip_list = ["ip3", "ip4"]
      class = "firewall"
  
    # ...
  

  Please refer to the snmp.yml file of Prometheus snmp_exporter for the profile. It is recommended to split module of different classes into different .yml configurations.

  Prometheus profile allows you to configure a separate community name for a module. This community name takes precedence over the community name configured for the input.

  switch:
    walk:
    ...
    get:
    ...
    metrics:
    ...
    auth:
      community: xxxxxxxxxxxx
  

• AutoDiscovery

The SNMP collector can discovery instance through Consul service, and the service injection format can be found on prom official website。

Configure SNMP device¶

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

SNMPv3 Example¶

We take an snmpd service on Linux as an example to demonstrate how to collecting SNMPv3 data.

• On an Ubuntu machine, install the snmpd service:

  sudo apt install snmp snmpd libsnmp-dev
  

• Prepare a simple snmpd.conf configuration as follows:

  my-snmpd.conf

  # Set the UDP 161 port
  agentaddress udp:161
  
  # Define a user and related authentication configurations
  createUser snmpv3user1 SHA "authPassAgent1" AES "privPassAgent1"
  
  # Grant user access permissions (rouser: read-only, rwuser: read-write)
  rouser snmpv3user1 priv .1.3.6
  

• Stop the snmpd service first, then manually start the snmpd process:

  sudo /usr/sbin/snmpd -f -Lo -C \
    -p x.pid -Ddump,usm,acl,header,context,pdu,snmpv3 \
    -c my-snmpd.conf
  

• Use the snmpwalk command to test, which is expected to output extensive OID device information:

  snmpwalk -v3 -l authPriv \
    -u snmpv3user1 \
    -a SHA \
    -A "authPassAgent1" \
    -x AES \
    -X "privPassAgent1" \
    udp:127.0.0.1:161 .1.3.6.1.2.1.1
  

• If the snmpwalk command succeeds, enable the collector on DataKit to collect metrics via SNMPv3. The key configuration is as follows:

  conf.d/snmp/snmp.conf

  specific_devices = ["127.0.0.1"] # Do not use "localhost" here
  snmp_version     = 3
  port             = 161
  
  v3_user                = "snmpv3user1"
  v3_auth_protocol       = "SHA" # MD5/SHA/SHA224/SHA256/SHA384/SHA512 or empty
  v3_auth_key            = "authPassAgent1"
  v3_priv_protocol       = "AES" # DES/AES/AES192/AES192C/AES256/AES256C or empty
  v3_priv_key            = "privPassAgent1"
  # v3_context_engine_id = "" # Optional
  # v3_context_name      = "" # Optional
  

Metric¶

For all of the following data collections, the global election tags will added automatically, we can add extra tags in [inputs.snmp.tags] if needed:

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

snmp_metric¶

SNMP device metric data.

• Tags

• Metrics

Object¶

snmp_object¶

SNMP device object data.

• Tags

• Metrics

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.

Device not support¶

DataKit collects generic basic 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.

Can't see any metrics after 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.