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

  ## Number of OIDs retrieved in a single SNMP Get/GetBulk call. Default is 5.
  # oid_batch_size = 5

  ## Max repetitions used in SNMP GetBulk calls. Default is 10.
  # bulk_max_repetitions = 10

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

  ## Enable LLDP topology collection. Default is false. (optional)
  # enable_lldp = false

  ## LLDP collection interval, default is 10m. (optional)
  # lldp_interval = "10m"

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

Built-in Profile Format¶

A built-in Profile uses YAML to describe the device sysObjectID, OIDs to collect, metric types, tags, and metadata.

This format is suitable when:

• The built-in Profiles do not cover the device model;
• Vendor-specific MIB metrics need to be added;
• The device returns numeric values as String/OCTET STRING;
• Device metadata needs to be added.

Profile YAML is different from Zabbix Template and Prometheus snmp_exporter formats. Their fields cannot be mixed.

Prepare OID Information¶

Before writing a Profile, obtain the device MIB/OID manual and use snmpget or snmpwalk to verify the actual values returned by the device. At minimum, confirm:

• The sysObjectID, which is the value of OID 1.3.6.1.2.1.1.2.0;
• Whether each metric is a scalar or a table column;
• The metric OID, data type, meaning, and unit;
• The complete String/OCTET STRING value format;
• The table index and tag columns that distinguish each row.

Add a Profile¶

DataKit releases built-in Profiles to conf.d/snmp/profiles/ under the installation directory, and this directory may be overwritten during startup or upgrade. To add a site-specific Profile or override a built-in Profile, place the YAML file in conf.d/snmp/extra_profiles/. DataKit merges both directories during the default Profile loading flow, with extra_profiles taking precedence.

Example:

/usr/local/datakit/conf.d/snmp/extra_profiles/vendor-router.yaml

File requirements:

• The extension must be .yaml;
• The file name must not start with _; files starting with _ are inheritance templates only;
• If a file has the same name as a built-in Profile, the file in extra_profiles takes precedence; to keep the built-in content, extend the same file name in the supplemental Profile;
• Different file names should not use the same sysobjectid, otherwise automatic matching treats them as duplicate Profiles.

Restart DataKit after adding the file.

Basic Structure¶

extends:
  - generic-router.yaml

sysobjectid: 1.3.6.1.4.1.<enterprise_id>.<product_id>

device:
  vendor: vendor_name

static_tags:
  - "device_type:router"

metadata:
  device:
    fields:
      model:
        symbol:
          OID: 1.3.6.1.4.1.<enterprise_id>.1.1.0
          name: vendorModel

metric_tags:
  - symbol:
      OID: 1.3.6.1.2.1.1.5.0
      name: sysName
    tag: snmp_host

metrics:
  - MIB: VENDOR-MIB
    symbol:
      OID: 1.3.6.1.4.1.<enterprise_id>.2.1.0
      name: vendor.system.cpu_usage
      metric_type: gauge

Root-level fields:

MIB and table improve YAML readability but do not determine which SNMP queries are executed. DataKit queries the OIDs configured in symbol, symbols, metric_tags, and metadata.

Inherit Profiles¶

Use extends to inherit existing Profiles. Metrics, tags, and metadata from inherited Profiles are merged into the current Profile, reducing duplicate standard MIB configuration.

extends:
  - _base.yaml
  - _generic-if.yaml

Built-in Profiles are located in conf.d/snmp/profiles/, and site-specific supplemental Profiles are located in conf.d/snmp/extra_profiles/. Before writing YAML, check the files starting with _ in the built-in directory and select reusable templates provided by the current DataKit version. Common templates include:

Files starting with _ are inheritance templates and do not independently participate in automatic sysObjectID matching. A complete Profile without the _ prefix can also be inherited. For example:

extends:
  - generic-router.yaml

generic-router.yaml already inherits _base.yaml, _generic-if.yaml, _generic-ip.yaml, _generic-tcp.yaml, _generic-udp.yaml, and _generic-ospf.yaml. Do not inherit these files again after inheriting generic-router.yaml.

For a Cisco device, inherit the common Cisco template and add device-specific metrics:

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

sysobjectid: 1.3.6.1.4.1.9.1.<product_id>

Notes:

• File names in extends are resolved from conf.d/snmp/extra_profiles/ first, then from conf.d/snmp/profiles/;
• A same-name Profile in extra_profiles can extend its own file name to inherit the built-in Profile with the same name;
• Multiple and nested inheritance are supported, but circular inheritance is not allowed;
• Metrics, dynamic tags, and static tags are appended during merging;
• A metadata field defined by the current Profile is not overwritten by inherited content;
• Do not inherit a template that an upper-level Profile already includes, or duplicate metrics and tags may be generated;
• More inherited modules result in more OID queries. Select modules according to the MIBs supported by the device.

sysObjectID Matching¶

Exact match:

sysobjectid: 1.3.6.1.4.1.99999.1.2

Wildcard match:

sysobjectid: 1.3.6.1.4.1.99999.*

Match multiple models:

sysobjectid:
  - 1.3.6.1.4.1.99999.1.*
  - 1.3.6.1.4.1.99999.2.*

When multiple Profiles match, DataKit selects the more specific rule. Different Profiles must not define the same sysobjectid. Use vendor- or product-specific values whenever possible to prevent a broad rule from matching unrelated devices.

For example, 1.3.6.1.4.1.8072.3.2.10 is a common Net-SNMP Linux sysObjectID, not a value exclusive to a specific device vendor.

Scalar Metrics¶

A scalar has one value and is defined with symbol. Scalar OIDs usually end with .0:

metrics:
  - MIB: VENDOR-SYSTEM-MIB
    symbol:
      OID: 1.3.6.1.4.1.99999.1.2.0
      name: vendor.system.cpu_usage
      metric_type: gauge

Table Metrics¶

A table contains multiple rows. Use symbols to define the columns to collect and metric_tags to distinguish each row:

metrics:
  - MIB: IF-MIB
    table:
      OID: 1.3.6.1.2.1.2.2
      name: ifTable
    symbols:
      - OID: 1.3.6.1.2.1.2.2.1.10
        name: vendor.interface.in_octets
        metric_type: monotonic_count
      - OID: 1.3.6.1.2.1.2.2.1.16
        name: vendor.interface.out_octets
        metric_type: monotonic_count
    metric_tags:
      - symbol:
          OID: 1.3.6.1.2.1.31.1.1.1.1
          name: ifName
        tag: interface

A table must have at least one tag that distinguishes its rows. Otherwise, multiple rows may have identical tags and only one row will be retained.

Tags can also be generated from the OID row index. index starts at 1:

metric_tags:
  - index: 1
    tag: disk_index

For a composite row index of 3.24, the following configuration generates slot:3 and port:24:

metric_tags:
  - index: 1
    tag: slot
  - index: 2
    tag: port

Convert String Values to Numbers¶

Metric field values must be numeric. A numeric String/OCTET STRING such as "52.20" can be converted directly. If the value contains a unit or other characters, use extract_value to extract the first capture group.

For a device value of STRING: "5331MB":

- OID: 1.3.6.1.4.1.99999.2.1.4
  name: vendor.disk.used
  extract_value: '^([0-9]+[.]?[0-9]*)MB$'
  metric_type: gauge

For a device value of STRING: "52.20%":

- OID: 1.3.6.1.4.1.99999.2.1.6
  name: vendor.disk.used_percent
  extract_value: '^([0-9]+[.]?[0-9]*)%?$'
  metric_type: gauge

Notes:

• The regular expression must contain at least one capture group. DataKit only uses the first group;
• Enclose regular expressions in single quotes and use ^ and $ to match the complete value;
• Go regular expression syntax is used. Lookahead and lookbehind are not supported;
• A value is not reported when the regular expression does not match;
• Plain text String values should be configured as tags or metadata instead of time-series metric values.

Metric Types and Value Scaling¶

The following metric_type values are recommended for custom Profiles:

metric_type can be configured on an individual symbol, or at the table metric root to apply to all its symbols. A value configured on an individual symbol takes precedence. When omitted, DataKit infers the type from the SNMP return type and uses gauge when it cannot infer a type.

Use scale_factor for numeric conversion. For example, if the device returns 5234 but the actual value is 52.34%:

- OID: 1.3.6.1.4.1.99999.1.2.0
  name: vendor.system.cpu_usage
  scale_factor: 0.01
  metric_type: gauge

scale_factor only affects the final reported metric value. For a String metric, use extract_value first and then apply scale_factor.

Report a Fixed Value of 1¶

When a table represents a set of entities but has no suitable numeric column, use constant_value_one to report a fixed value of 1 for every row:

metrics:
  - MIB: VENDOR-DISK-MIB
    table:
      OID: 1.3.6.1.4.1.99999.3.1
      name: vendorDiskTable
    symbols:
      - name: vendor.disk.present
        constant_value_one: true
    metric_tags:
      - symbol:
          OID: 1.3.6.1.4.1.99999.3.1.1
          name: diskName
        tag: disk_name
      - symbol:
          OID: 1.3.6.1.4.1.99999.3.1.2
          name: diskState
        tag: disk_state
        mapping:
          1: normal
          2: warning
          3: failed

constant_value_one can only be used in table symbols, not scalar metrics. Do not configure an OID for this symbol, but configure its name and at least one OID-based metric_tags.symbol without index_transform, so DataKit can discover the table rows.

Tags¶

Use root-level static_tags to add fixed tags:

static_tags:
  - "device_type:router"
  - "environment:production"

Root-level metric_tags generate dynamic tags from scalar OIDs and apply them to device metrics:

metric_tags:
  - symbol:
      OID: 1.3.6.1.2.1.1.5.0
      name: sysName
    tag: snmp_host

Within a table, metric_tags can use mapping to convert raw values into readable tag values:

metric_tags:
  - symbol:
      OID: 1.3.6.1.4.1.99999.3.1.2
      name: diskState
    tag: disk_state
    mapping:
      1: normal
      2: warning
      3: failed

Use match and tags to generate multiple tags from one table column value:

metric_tags:
  - symbol:
      OID: 1.3.6.1.4.1.99999.4.1.2
      name: interfaceLabel
    match: '^([A-Za-z]+)-([0-9]+)$'
    tags:
      interface_type: '$1'
      interface_number: '$2'

For a raw value of ethernet-12, this generates interface_type:ethernet and interface_number:12. A non-empty tags mapping is required when match is configured. No tag is generated when the regular expression does not match.

When the metric table and tag source table use different index structures, use index_transform to extract and rebuild the index:

metric_tags:
  - symbol:
      OID: 1.3.6.1.4.1.99999.5.1.2
      name: parentName
    index_transform:
      - start: 1
        end: 2
      - start: 6
        end: 7
    tag: parent_name

For a current index of 1.2.3.4.5.6.7.8, the transformed index is 2.3.7.8. Both start and end are zero-based, and the value at end is included. This option is only needed for cross-table association.

Metadata¶

A custom Profile can add device metadata through metadata.device. Supported fields are name, description, sys_object_id, location, serial_number, vendor, version, product_name, model, os_name, os_version, os_hostname, and type. A field can obtain its value from a scalar OID or use a fixed value:

metadata:
  device:
    fields:
      name:
        symbol:
          OID: 1.3.6.1.2.1.1.5.0
          name: sysName
      serial_number:
        symbol:
          OID: 1.3.6.1.4.1.99999.1.1.0
          name: vendorSerialNumber
      vendor:
        value: vendor_name
      type:
        value: router

A field can define multiple candidate symbols. DataKit uses the first OID that returns a value. Use match_pattern and match_value to extract or replace text:

metadata:
  device:
    fields:
      model:
        symbols:
          - OID: 1.3.6.1.4.1.99999.1.2.0
            name: vendorModel
          - OID: 1.3.6.1.2.1.1.1.0
            name: sysDescr
            match_pattern: 'Model[=: ]+([A-Za-z0-9._-]+)'
            match_value: '$1'

When match_value is omitted, the first capture group $1 is used. If the regular expression does not match, DataKit tries the next candidate symbol.

After inheriting _generic-if.yaml or generic-router.yaml, common interface metadata is already included and usually does not need to be configured again.

Metric Naming¶

Metric names are converted before reporting according to these rules:

1. If the name contains an underscore _, all dots . are replaced with underscores _;
2. If the name contains no underscore _, dots . are removed and the first letter after each dot is converted to uppercase;
3. A name without dots . remains unchanged.

Examples:

The same conversion applies to tag keys but not tag values.

Use one naming style consistently within a Profile. A dot-separated name without underscores, such as vendor.disk.used, or an underscore name without dots, such as vendor_disk_used, can be used. Avoid mixing dots and underscores because all dots will then be converted to underscores. Existing built-in Profiles commonly use names such as huawei.hwEntityTemperature, which is reported as huaweiHwEntityTemperature.

Complete Example¶

The following example inherits common router metrics and collects device metadata, a numeric scalar, String disk metrics, and an entity-presence metric:

extends:
  - generic-router.yaml

sysobjectid: 1.3.6.1.4.1.99999.1.2

device:
  vendor: vendor_name

metadata:
  device:
    fields:
      model:
        symbol:
          OID: 1.3.6.1.4.1.99999.1.1.0
          name: vendorModel

metrics:
  - MIB: VENDOR-SYSTEM-MIB
    symbol:
      OID: 1.3.6.1.4.1.99999.1.2.0
      name: vendor.system.cpu_usage
      metric_type: gauge

  - MIB: VENDOR-DISK-MIB
    table:
      OID: 1.3.6.1.4.1.99999.2.1
      name: vendorDiskTable
    symbols:
      - OID: 1.3.6.1.4.1.99999.2.1.4
        name: vendor.disk.used
        extract_value: '^([0-9]+[.]?[0-9]*)MB$'
        metric_type: gauge
      - OID: 1.3.6.1.4.1.99999.2.1.6
        name: vendor.disk.used_percent
        extract_value: '^([0-9]+[.]?[0-9]*)%?$'
        metric_type: gauge
      - name: vendor.disk.present
        constant_value_one: true
    metric_tags:
      - index: 1
        tag: disk_index
      - symbol:
          OID: 1.3.6.1.4.1.99999.2.1.2
          name: diskName
        tag: disk_name

Validation and Troubleshooting¶

Common issues:

• Profile not matched: Check the device's actual sysObjectID, wildcard range, and whether a more specific matching rule exists;
• YAML not loaded: Check the file extension, file name, indentation, and Profile validation errors in the DataKit logs;
• No OID data: Run snmpget or snmpwalk with the same SNMP version and authentication settings as DataKit;
• String metric not reported: Check that extract_value contains a capture group and matches the complete actual value;
• Only one table row reported: Add metric_tags that distinguish every row;
• Metric skipped: Confirm that the final value can be converted to a number, and check metric_type and scale_factor.

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
  

LLDP Network Topology Collection¶

DataKit supports collecting LLDP (Link Layer Discovery Protocol) neighbor information from network devices via SNMP protocol for automatic network topology construction.

What is LLDP¶

LLDP is a standardized link-layer protocol that allows network devices (such as switches and routers) to broadcast their identity and capability information to directly connected neighbor devices. By collecting LLDP data, you can:

• Automatically discover network topology relationships
• Understand physical connection status between devices
• Obtain neighbor device port, hostname, system description, and other information
• Build visualized network topology diagrams

Enable LLDP Collection¶

Enable LLDP collection in DataKit's SNMP configuration:

[[inputs.snmp]]
  ## Enable LLDP topology collection
  enable_lldp = true

  ## LLDP collection interval (optional, default 10 minutes)
  lldp_interval = "10m"

Device Configuration Requirements¶

Network devices need to:

• Enable LLDP

• Configure SNMP access to LLDP MIB

Verify Configuration¶

Verify LLDP neighbors on device:

# Huawei device
display lldp neighbor

# Cisco device
show lldp neighbor

Verify SNMP can query LLDP data from DataKit host:

# SNMPv2c verification
snmpwalk -v2c -c [COMMUNITY_STRING] [DEVICE_IP] 1.0.8802.1.1.2.1.4.1

# SNMPv3 verification
snmpwalk -v3 -u [USERNAME] -l authPriv \
  -a SHA -A [AUTH_PASSWORD] \
  -x AES -X [PRIV_PASSWORD] \
  [DEVICE_IP] 1.0.8802.1.1.2.1.4.1

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.

Object¶

snmp_object¶

SNMP device object data.

Logging¶

snmp_lldp¶

SNMP LLDP (Link Layer Discovery Protocol) topology data.

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 Supported¶

DataKit collects common baseline metrics from SNMP devices. If the collected data does not contain the required metrics, you may need to add a custom Profile.

To do this, obtain the OID manual for the device model from the vendor's 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.