SNMP

本書では SNMP データの収集を説明します。

用語¶

• SNMP (Simple network management protocol)：物理ネットワークデバイスの情報を収集するプロトコル。
• OID (Object identifier)：ポーリングで値を取得するデバイス上の一意の ID またはアドレス。例：CPU、ファン速度。
• sysOID (System object identifier)：デバイス種別を定義する固有のアドレス。例：Meraki の基本 sysOID は「1.3.6.1.4.1.29671」です。
• MIB (Managed information base)：関連する OID と定義のデータベースまたは一覧。例えば「IF-MIB」にはデバイスインターフェースの情報を表す OID が含まれます。

SNMP プロトコルについて¶

SNMP には v1/v2c/v3 の 3 バージョンがあります：

• v1 と v2c は互換です。多くのデバイスは v2c と v3 のみ提供します。v2c は互換性が高く、古いデバイスではこのバージョンのみ対応する場合があります。
• 高いセキュリティが必要なら v3 を選びます。セキュリティが以前のバージョンとの主な違いです。

DataKit はすべてのバージョンに対応しています。

v1/v2c の選択¶

v1/v2c では認証用の v2_community_string（コミュニティ名、暗号化されていないパスワード）が必要です。デバイスによっては読み取り専用と読み書き可能を区別します：

• 読み取り専用：内部メトリクスを取得できますが、設定変更はできません。DataKit にはこれで十分です。
• 読み書き可能：内部メトリクスの取得と一部の設定変更が可能です。

v3 の選択¶

v3 では v3_user/v3_auth_protocol/v3_auth_key/v3_priv_protocol/v3_priv_key などをデバイスの要件と設定に合わせて指定します。

設定¶

コレクター設定¶

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

  ## Collect LLDP/CDP topology links in snmp_object. Default is false. (optional)
  ## Built-in Profiles only; follows object_interval and is independent of enable_lldp.
  ## LLDP is preferred, with CDP used as a fallback.
  # collect_topology = false

  ## Enable standalone LLDP neighbor collection and report snmp_lldp logging data.
  ## Default is false. (optional)
  ## Avoid enabling this together with collect_topology unless both outputs are needed.
  # 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". It is an identity tag and cannot be overridden by custom tags.
  # 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.
    # source = "traps"

各種設定形式¶

組み込み Profile 形式¶

組み込み Profile は YAML で sysObjectID、収集 OID、メトリクス型、tag、メタデータを定義します。

次の場合に適しています：

• 組み込み Profile がデバイス型番に未対応。
• ベンダー独自の MIB メトリクスを追加する場合。
• 数値が String/OCTET STRING で返る場合。
• デバイスメタデータを補足する場合。

Profile YAML は Zabbix Template や Prometheus snmp_exporter と異なる形式で、フィールドを混用できません。

OID 情報の準備¶

Profile 作成前に MIB/OID マニュアルを入手し、snmpget または snmpwalk で実際の応答を確認します。少なくとも以下を確認してください：

• sysObjectID、つまり OID 1.3.6.1.2.1.1.2.0 の値。
• メトリクスがスカラーかテーブル列か。
• メトリクス OID、型、意味、単位。
• String/OCTET STRING の完全な応答形式。
• テーブルインデックスと各行を区別する tag 列。

Profile の追加¶

組み込み Profile はインストール先の conf.d/snmp/profiles/ に展開され、起動・更新時に上書きされる場合があります。追加・上書き用 YAML は conf.d/snmp/extra_profiles/ に配置してください。既定の読み込み時に両方を統合し、extra_profiles を優先します。

例：

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

ファイルの要件：

• 拡張子は .yaml。
• ファイル名を _ で始めないでください。_ で始まるものは継承テンプレート専用です。
• 同名なら extra_profiles を優先します。元の組み込み内容も継承するには、同じファイル名を extends に指定します。
• 別名のファイルに同じ sysobjectid を指定しないでください。自動照合で重複 Profile として扱われます。

追加後は DataKit を再起動します。

基本構造¶

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

ルートフィールドの説明：

MIB と table は YAML の可読性を高めるもので、SNMP クエリは決定しません。実際に問い合わせるのは symbol、symbols、metric_tags、metadata の OID です。

Profile の継承¶

extends は既存 Profile を継承します。メトリクス、tag、メタデータを統合し、標準 MIB の重複設定を減らせます。

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

組み込み Profile は conf.d/snmp/profiles/、ユーザー追加分は conf.d/snmp/extra_profiles/ にあります。YAML 作成前に _ で始まるファイルを確認し、DataKit のバージョンに合うテンプレートを選んでください。代表例：

_ で始まるファイルは継承専用で、単独の sysObjectID 自動照合には参加しません。generic-router.yaml など _ のない完全な Profile も継承できます：

extends:
  - generic-router.yaml

generic-router.yaml は _base.yaml、_generic-if.yaml、_generic-ip.yaml、_generic-tcp.yaml、_generic-udp.yaml、_generic-ospf.yaml を継承済みです。重ねて指定する必要はありません。

Cisco デバイスは共通 Cisco テンプレートを継承し、固有メトリクスを追加できます：

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

sysobjectid: 1.3.6.1.4.1.9.1.<product_id>

注意：

• extends は conf.d/snmp/extra_profiles/、次に conf.d/snmp/profiles/ の順に検索します。
• extra_profiles の Profile は extends に自身の名前を指定して同名の組み込み Profile を継承できます。
• 複数・多段継承に対応しますが、循環継承はできません。
• メトリクス、動的 tag、静的 tag は追加方式で統合します。
• 現在の Profile で定義した同名メタデータは上書きしません。
• 上位 Profile に含まれるテンプレートを重複継承すると、メトリクスや tag が重複する場合があります。
• 継承する共通モジュールが増えるほど OID クエリも増えます。デバイスが対応する MIB に合わせて選んでください。

sysObjectID の照合¶

完全一致：

sysobjectid: 1.3.6.1.4.1.99999.1.2

ワイルドカード一致：

sysobjectid: 1.3.6.1.4.1.99999.*

複数モデルとの一致：

sysobjectid:
  - 1.3.6.1.4.1.99999.1.*
  - 1.3.6.1.4.1.99999.2.*

複数の Profile が一致すると、最も具体的な規則を選びます。別の Profile に同一の sysobjectid を指定しないでください。他のデバイスとの誤一致を防ぐため、ベンダーや製品固有の値を使います。

例えば 1.3.6.1.4.1.8072.3.2.10 は一般的な Net-SNMP Linux の sysObjectID で、特定ベンダー専用ではありません。

スカラーメトリクス¶

スカラーは単一の値で、symbol で定義します。OID は通常 .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

テーブルメトリクス¶

テーブルは複数行です。symbols で収集列、metric_tags で各行の識別子を定義します：

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

行を区別する tag が最低 1 つ必要です。ない場合、複数行が同じ tag になり、最終的に 1 行しか保持できない場合があります。

OID の行インデックスからも tag を生成できます。index は 1 始まりです：

metric_tags:
  - index: 1
    tag: disk_index

完全なインデックスが 3.24 なら、次の設定で slot:3 と port:24 を生成します：

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

String から数値への変換¶

メトリクス値は数値である必要があります。"52.20" のような数値のみの String/OCTET STRING は直接変換できます。単位などを含む場合は extract_value の第 1 捕捉グループから抽出します。

デバイスの応答が 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

デバイスの応答が 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

注意：

• 正規表現には捕捉グループが必要で、DataKit は最初のグループのみ使用します。
• 正規表現は単一引用符で囲み、^ と $ で全体一致させることを推奨します。
• Go 正規表現を使用します。先読み・後読みは未対応です。
• 正規表現が一致しない値は送信しません。
• 通常の文字列は時系列メトリクス値ではなく、tag またはメタデータにしてください。

メトリクス型と数値換算¶

カスタム Profile では次の metric_type を推奨します：

個別の symbol、またはテーブル全体の全 symbols に設定できます。個別設定を優先します。未設定なら SNMP の返却型から推定し、推定できなければ gauge とします。

scale_factor で数値を換算します。例：返却値 5234 が実際は 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 は最終的なメトリクス数値のみに適用します。String は先に extract_value で抽出し、その後に換算できます。

固定値 1 の送信¶

テーブルがエンティティを表し適切な数値列がない場合、constant_value_one で各行に 1 を送信できます：

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 はテーブルの symbols 専用で、スカラーには使えません。メトリクス OID は指定せず、name は必須です。行検出用に、OID があり index_transform のない metric_tags.symbol を最低 1 つ設定します。

タグ¶

Profile ルートの static_tags は固定 tag を追加します：

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

Profile ルートの metric_tags はスカラー OID からデバイスメトリクス用の動的 tag を生成します：

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

テーブル内の metric_tags は mapping で元の値を読みやすい tag に変換できます：

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

match と tags で 1 つの列値から複数の tag を生成できます：

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'

ethernet-12 から interface_type:ethernet と interface_number:12 を生成します。match には空でない tags が必須で、正規表現が不一致なら tag は生成しません。

メトリクステーブルと tag 元テーブルのインデックス構造が異なる場合、index_transform で切り出して再構成できます：

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

1.2.3.4.5.6.7.8 は 2.3.7.8 になります。start、end は 0 始まりで、end の位置も含みます。テーブル間の関連付け時のみ必要です。

メタデータ¶

metadata.device で name、description、sys_object_id、location、serial_number、vendor、version、product_name、model、os_name、os_version、os_hostname、type を補足できます。値はスカラー OID または固定 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

複数候補の symbols を指定でき、最初に値が取得できた OID を使用します。match_pattern と match_value でテキストを抽出・置換できます：

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'

match_value を省略すると第 1 捕捉グループ $1 を使用し、不一致なら次の symbol を試します。

_generic-if.yaml または generic-router.yaml を継承すると共通インターフェースメタデータを含むため、通常は再設定不要です。

メトリクスの命名¶

メトリクス名は次の規則で変換して送信します：

1. 名前に _ があれば、すべての . を _ に変換します。
2. _ がなければ . を削除し、その直後の文字を大文字にします。
3. . がなければ変更しません。

例：

この変換は tag キーにも適用しますが、値は変更しません。

Profile 内では命名を統一します。vendor.disk.used のようなドット階層名、または vendor_disk_used のようなアンダースコア名を使えます。混用するとドットがアンダースコアになるため避けてください。組み込みでよく使う huawei.hwEntityTemperature は huaweiHwEntityTemperature として送信されます。

完全な例¶

次の例は汎用ルーターメトリクスを継承し、デバイスメタデータ、数値スカラー、String 型ディスクメトリクス、エンティティ存在メトリクスを収集します：

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

検証とトラブルシューティング¶

よくある問題：

• Profile 不一致：実際の sysObjectID、ワイルドカード範囲、より具体的な規則を確認します。
• YAML 未読込：拡張子、ファイル名、インデント、DataKit ログの Profile 検証エラーを確認します。
• OID データなし：DataKit と同じ SNMP バージョン・認証情報で snmpget/snmpwalk を実行します。
• String メトリクス未送信：extract_value の捕捉グループと実際の完全な値への一致を確認します。
• テーブルが 1 行のみ：各行を区別する metric_tags を追加します。
• メトリクスがスキップされる：数値変換が可能か確認し、metric_type と scale_factor を確認します。

Zabbix 形式¶

• 設定

    [[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 = "firewall"
  
    # ...
  

  profile_name はフルパスまたはファイル名です。ファイル名のみなら ./conf.d/snmp/userprofiles/ に配置します。

  Zabbix 公式またはコミュニティから設定をダウンロードできます。

  ダウンロードした yaml や xml は必要に応じて編集できます。

• 自動検出

  • 自動検出では取り込んだ複数の yaml 内の収集規則と照合します。
  • クラス C の範囲を推奨します。クラス B では遅くなる場合があります。

  • yaml に一致しない場合、デバイスのベンダー識別コードが定義されていない可能性があります。

    • yaml の items に oid を追加して自動照合を補助できます。

    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
    

    • 追加する oid は次のコマンドで取得します。末尾の .0.0.0.0 は不要なメトリクスを防ぎます。

    $ 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 形式¶

• 設定

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

  Profile は Prometheus snmp_exporter の snmp.yml を参考にしてください。 class が異なる module は別の .yml に分けることを推奨します。

  Prometheus Profile は module ごとに community を指定でき、コレクター設定より優先します。

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

• 自動検出

  SNMP は Consul サービス検出に対応します。登録形式は Prometheus 公式を参照してください。

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

収集対象 SNMP デバイスの設定¶

デバイスでは通常 SNMP が既定で無効です。管理画面で有効にし、適切なプロトコルバージョンと情報を設定してください。

# v2c 用
snmpwalk -O bentU -v 2c -c [community string] [SNMP_DEVICE_IP] 1.3.6
# v3 用
snmpwalk -v 3 -u user -l authPriv -a sha -A [认证密码] -x aes -X [加密密码] [SNMP_DEVICE_IP] 1.3.6

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

SNMPv3 の例¶

Linux の snmpd を例に SNMP v3 での収集を説明します。

• Ubuntu に snmpd サービスをインストールします：

  sudo apt install snmp snmpd libsnmp-dev
  

• 次の簡単な snmpd.conf を用意します：

  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
  

• snmpd サービスを停止し、プログラムを手動起動します：

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

• snmpwalk で確認します。多数の OID デバイス情報が出力されるはずです：

  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
  

• snmpwalk が成功したら、DataKit でコレクターを有効にして SNMPv3 で収集できます。主要設定：

  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 ネットワークトポロジー収集¶

DataKit は SNMP でネットワーク機器の LLDP（Link Layer Discovery Protocol）隣接情報を収集し、トポロジーを自動構築します。

LLDP とは¶

LLDP は標準のリンク層プロトコルで、スイッチやルーターが直接接続された隣接機器に識別情報と機能を通知します。収集すると次が可能です：

• トポロジー関係の自動検出
• デバイス間の物理接続の把握
• 隣接機器のポート、ホスト名、システム説明の取得
• ネットワークトポロジーの可視化

LLDP 収集の有効化¶

LLDP 隣接情報は snmp_object のリンクメタデータとして付加することを推奨します：

[[inputs.snmp]]
  ## オブジェクトとともに LLDP 隣接情報を収集し、トポロジーリンクを snmp_object の links に書き込みます
  collect_topology = true

collect_topology は既定で無効です。有効時はオブジェクト収集周期で LLDP/CDP MIB を追加照会し、ローカルと対向のデバイス・インターフェース情報を JSON 配列にして snmp_object の links に書き込みます。LLDP を優先し、リンクがない場合のみ CDP にフォールバックします。

snmp_object を送信する組み込み Profile モード専用で、ユーザー Profile の snmp_<class> には適用しません。

links フィールド¶

links をデコードした LLDP リンクの例です。// はフィールド説明のコメントです：

[
  {
    // ローカルデバイスのトポロジー隣接レコード ID。
    // LLDP 形式: <device_namespace>:<管理 IP>:<lldpRemLocalPortNum>.<lldpRemIndex>;
    // CDP 形式: <device_namespace>:<管理 IP>:<cdpCacheIfIndex>.<cdpCacheDeviceIndex>。
    "id": "default:192.0.2.10:7.1",
    // 隣接データのソース: lldp または cdp。
    "source_type": "lldp",
    // 収集インテグレーション名。現在は snmp 固定。
    "integration": "snmp",
    // DataKit が直接収集するローカルリンク端点。
    "local": {
      // ローカルデバイス。
      "device": {
        // 解決済みローカルデバイス ID: <device_namespace>:<管理 IP>。
        "resolved_id": "default:192.0.2.10"
      },
      // ローカルインターフェース。
      "interface": {
        // 解決済みローカルインターフェース ID: <local.device.resolved_id>:<ifIndex>。
        // LLDP ローカルポートを IF-MIB に関連付けできない場合は欠落することがあります。
        "resolved_id": "default:192.0.2.10:12",
        // LLDP の lldpLocPortId。CDP リンクでは現在空文字列。
        "id": "82:a5:6e:a5:c9:01",
        // lldpLocPortIdSubtype から変換したローカルポート ID 型。CDP では通常欠落。
        "id_type": "mac_address"
      }
    },
    // 隣接プロトコルで検出した対向端点。DataKit が直接収集しているとは限りません。
    "remote": {
      // 対向デバイス。
      "device": {
        // LLDP の lldpRemChassisId または CDP の cdpCacheDeviceId。
        "id": "01:00:00:00:01:02",
        // lldpRemChassisIdSubtype から変換した LLDP Chassis ID 型。CDP では通常欠落。
        "id_type": "mac_address",
        // LLDP の lldpRemSysName または CDP の cdpCacheSysName。
        "name": "switch-b",
        // LLDP の lldpRemSysDesc または CDP の cdpCacheVersion。
        "description": "remote switch",
        // 対向の管理 IP。LLDP はリモート管理アドレス表のインデックスから解析。
        // CDP は主、予備、キャッシュの管理アドレスを順に試します。未送信なら欠落。
        "ip_address": "10.250.0.6"
      },
      // 対向インターフェース。
      "interface": {
        // LLDP の lldpRemPortId または CDP の cdpCacheDevicePort。
        "id": "Ethernet1/7",
        // LLDP 対向ポート ID 型。CDP は interface_name 固定。
        "id_type": "interface_name",
        // LLDP の lldpRemPortDesc。CDP では通常欠落。
        "description": "remote uplink"
      }
    }
  }
]

LLDP のデバイス・ポート ID 型には mac_address、network_address、interface_name、interface_alias、port_component、local などがあります。構造上必須のフィールド以外は、名前、説明、管理 IP、未解決のオブジェクト ID が欠落する場合があります。

既存の enable_lldp は独立した収集機能で、lldp_interval ごとに snmp_lldp ログを送信します。既存設定との互換性のため維持します：

[[inputs.snmp]]
  enable_lldp = true
  lldp_interval = "10m"

両スイッチは独立し、既定は false です。通常はどちらか一方で十分です。両方有効なら各周期で LLDP を照会し、オブジェクトリンクとログの両方を生成します。

対象デバイスの設定要件¶

ネットワーク機器側で必要な設定：

• LLDP を有効化

• LLDP MIB への SNMP アクセスを許可

設定の検証¶

デバイス上で LLDP 隣接情報を確認：

# Huawei device
display lldp neighbor

# Cisco device
show lldp neighbor

DataKit ホストから SNMP で LLDP を照会できるか確認：

# 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

メトリクス¶

以下の収集データには既定でグローバル選出 tag を付加します。[inputs.snmp.tags] で他の tag も指定できます：

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

snmp_metric¶

SNMP device metric data.

オブジェクト¶

snmp_object¶

SNMP device object data.

ログ¶

snmp_lldp¶

SNMP LLDP (Link Layer Discovery Protocol) topology data.

FAQ¶

DataKit はどのようにデバイスを検出しますか？¶

指定デバイスと自動検出の 2 モードに対応し、同時に有効化できます。

指定モードでは対象 IP と SNMP 通信し、オンライン状態を把握します。

自動検出では指定サブネットの全アドレスに順次 SNMP パケットを送り、応答が Profile と一致すれば SNMP デバイスが存在すると判断します。

デバイスが収集に未対応¶

DataKit は SNMP デバイスの共通基本メトリクスを収集できます。必要なメトリクスがない場合は、カスタム Profile が必要です。

そのために、ベンダー公式サイトから対象型番の OID マニュアルを入手する必要がある場合があります。

SNMP 収集を有効にしてもメトリクスが表示されない¶

デバイスの ACL/ファイアウォール規則でアクセスを許可してください。

DataKit ホストで snmpwalk -O bentU -v 2c -c <COMMUNITY_STRING> <IP_ADDRESS>:<PORT> 1.3.6 を実行します。応答なしのタイムアウトは、メトリクス収集が何かに遮断されている可能性を示します。