maxwo/snmp-notifier

SNMP Notifier

镜像概述和主要用途

snmp_notifier 接收来自 Prometheus Alertmanager 的告警，并将其作为 SNMP 陷阱进行路由。该工具主要用于与较旧的监控和告警系统（如 Nagios 或 Centreon）集成，实现 Prometheus 告警向传统 SNMP 监控系统的转发。

核心功能和特性

• 接收 Prometheus Alertmanager 发送的告警并转换为 SNMP 陷阱
• 支持 SNMP v2c 和 v3 版本
• 为每个陷阱分配唯一 ID，支持告警更新或解决时发送状态更新
• 允许通过告警标签指定 OID，或使用默认 OID
• 支持自定义陷阱描述模板和用户定义对象
• 可配置的告警严重性处理机制
• 提供 Web 接口用于接收告警和暴露指标

使用场景和适用范围

• 需要将 Prometheus 告警集成到现有 SNMP 监控基础设施的环境
• 企业级监控系统中需要统一告警通知渠道的场景
• 需要向传统网络管理系统转发云原生环境告警的场合
• 混合 IT 环境中实现统一告警管理的需求

安装方法

Helm Chart 安装

SNMP notifier 图表可通过 https://github.com/prometheus-community/helm-charts 获取：

console
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm install snmp-notifier prometheus-community/alertmanager-snmp-notifier --set 'snmpNotifier.snmpDestinations={my-snmp-server:162}'

请参考 https://github.com/prometheus-community/helm-charts/blob/main/charts/alertmanager-snmp-notifier/values.yaml 查看可用配置选项。

Docker 镜像安装

Docker 镜像可在 https://hub.docker.com/r/maxwo/snmp-notifier 获取：

console
docker pull maxwo/snmp-notifier

预编译二进制文件

预编译二进制文件可在项目的 https://github.com/maxwo/snmp_notifier/releases 获取。

手动编译

console
git clone https://github.com/maxwo/snmp_notifier.git
cd snmp_notifier
make build
./snmp_notifier

使用方法和配置说明

Docker 运行示例

console
docker run -d -p 9464:9464 \
  -e SNMP_NOTIFIER_COMMUNITY=my-secret-community \
  maxwo/snmp-notifier \
  --snmp.version=V2c \
  --snmp.destination=snmp-server:162 \
  --alert.severity-label=severity \
  --log.level=info

Docker Compose 配置示例

yaml
version: '3'
services:
  snmp-notifier:
    image: maxwo/snmp-notifier
    ports:
      - "9464:9464"
    environment:
      - SNMP_NOTIFIER_COMMUNITY=my-secret-community
    command:
      - --snmp.version=V2c
      - --snmp.destination=snmp-server:162
      - --alert.severity-label=severity
      - --log.level=info
    restart: unless-stopped

Prometheus 告警配置

可在告警标签中添加 OID 以标识要发送的陷阱类型：

如果未在告警中找到 OID，SNMP notifier 会使用默认 OID。这在希望所有告警共享相同 OID 时非常有用。

yaml
groups:
  - name: service
    rules:
      - alert: ServiceIsDown
        expr: up == 0
        for: 5m
        labels:
          severity: "critical"
          type: "service"
          oid: "1.3.6.1.4.1.123.0.10.1.1.1.5.1"
          environment: "production"
        annotations:
          description: "服务 {{ $labels.job }} 在 {{ $labels.instance }} 上已宕机"
          summary: "服务宕机告警"

Alertmanager 配置

应将 Alertmanager 配置为使用 SNMP notifier 作为告警接收器：

yaml
receivers:
  - name: "snmp_notifier"
    webhook_configs:
      - send_resolved: true
        url: http://snmp.notifier.service:9464/alerts

注意，send_resolved 选项允许 notifier 将陷阱状态更新为正常。

SNMP Notifier 配置

命令行参数

启动 snmp_notifier 可执行文件时使用 --help 标志查看可用选项：

console
$ ./snmp_notifier --help
usage: snmp_notifier [<flags>]

用于将 Prometheus 告警中继为 SNMP 陷阱的工具


标志:
  -h, --[no-]help                显示上下文相关帮助（也可尝试 --help-long 和 --help-man）。
      --web.listen-address=:9464 ...  
                                 用于公开指标和 Web 界面的地址。可重复多次指定多个地址。
                                 示例: `:9100` 或 `[::1]:9100` (HTTP), `vsock://:9100` (vsock)
      --web.config.file=""       可启用 TLS 或身份验证的配置文件路径。
                                 参见: https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md
      --alert.severity-label="severity"  
                                 用于查找告警严重性的标签。
      --alert.severities="critical,warning,info"  
                                 告警严重性的有序列表，从高优先级到低优先级。
      --alert.default-severity="critical"  
                                 未通过标签提供时使用的默认告警严重性。
      --snmp.version=V2c         SNMP 版本。当前支持 V2c 和 V3。
      --snmp.destination=127.0.0.1:162 ...  
                                 SNMP 陷阱服务器目标地址。
      --snmp.retries=1           SNMP 重试次数
      --snmp.timeout=5s          SNMP 超时时间
      --snmp.community="public"  SNMP 社区 (仅 V2c)。不建议通过命令行传递密钥，
                                 考虑使用 SNMP_NOTIFIER_COMMUNITY 环境变量替代。 ($SNMP_NOTIFIER_COMMUNITY)
      --[no-]snmp.authentication-enabled  
                                 启用 SNMP 身份验证 (仅 V3)。
      --snmp.authentication-protocol=MD5  
                                 密码加密协议 (仅 V3)。当前支持 MD5 和 SHA。
      --snmp.authentication-username=USERNAME  
                                 SNMP 身份验证用户名 (仅 V3)。不建议通过命令行传递密钥，
                                 考虑使用 SNMP_NOTIFIER_AUTH_USERNAME 环境变量替代。 ($SNMP_NOTIFIER_AUTH_USERNAME)
      --snmp.authentication-password=PASSWORD  
                                 SNMP 身份验证密码 (仅 V3)。不建议通过命令行传递密钥，
                                 考虑使用 SNMP_NOTIFIER_AUTH_PASSWORD 环境变量替代。 ($SNMP_NOTIFIER_AUTH_PASSWORD)
      --[no-]snmp.private-enabled  
                                 启用 SNMP 加密 (仅 V3)。
      --snmp.private-protocol=DES  
                                 SNMP 数据传输协议 (仅 V3)。当前支持 DES 和 AES。
      --snmp.private-password=SECRET  
                                 SNMP 私有密码 (仅 V3)。不建议通过命令行传递密钥，
                                 考虑使用 SNMP_NOTIFIER_PRIV_PASSWORD 环境变量替代。 ($SNMP_NOTIFIER_PRIV_PASSWORD)
      --snmp.security-engine-id=SECURITY_ENGINE_ID  
                                 SNMP 安全引擎 ID (仅 V3)。
      --snmp.context-engine-id=CONTEXT_ENGINE_ID  
                                 SNMP 上下文引擎 ID (仅 V3)。
      --snmp.context-name=CONTEXT_ENGINE_NAME  
                                 SNMP 上下文名称 (仅 V3)。
      --snmp.engine-start-time=""  
                                 指定引擎启动时间的 UNIX 时间戳（秒）。默认为主机启动时间。
      --trap.default-oid="1.3.6.1.4.1.98789.1"  
                                 默认陷阱 OID。
      --trap.oid-label="oid"     包含自定义陷阱 OID 的标签。
      --trap.resolution-default-oid=TRAP.RESOLUTION-DEFAULT-OID  
                                 解决状态陷阱 OID，如果与触发状态陷阱 OID 不同。
      --trap.resolution-oid-label=TRAP.RESOLUTION-OID-LABEL  
                                 包含自定义解决状态陷阱 OID 的标签，如果与触发状态陷阱 OID 不同。
      --trap.default-objects-base-oid="1.3.6.1.4.1.98789.2"  
                                 默认陷阱对象的基础 OID。
      --trap.description-template=description-template.tpl  
                                 陷阱描述模板。
      --trap.user-objects-base-oid="1.3.6.1.4.1.98789.3"  
                                 用户定义陷阱对象的基础 OID。
      --trap.user-object=4=user-object-template.tpl ...  
                                 用户对象子 OID 和模板，例如 --trap.user-object=4=new-object.template.tpl
                                 用于添加子对象到陷阱，使用给定的模板文件。可多次使用此标志添加多个用户对象。
      --log.level=info           仅记录指定严重性或更高级别的消息。选项: [debug, info, warn, error]
      --log.format=logfmt        日志消息输出格式。选项: [logfmt, json]
      --[no-]version             显示应用程序版本。

环境变量

建议使用以下环境变量设置 SNMP 密钥：

使用示例

简单用法

以下是使用默认配置接收的 2 个示例陷阱，包括 2 个触发状态的告警和 1 个已解决的告警。

陷阱包含 3 个字段：

• 陷阱唯一 ID
• 告警/陷阱状态
• 告警描述

console
$ snmptrapd -m ALL -m +SNMP-NOTIFIER-MIB -f -Of -Lo -c scripts/snmptrapd.conf
 Agent Address: 0.0.0.0
 Agent Hostname: localhost
 Date: 1 - 0 - 0 - 1 - 1 - 1970
 Enterprise OID: .
 Trap Type: Cold Start
 Trap Sub-Type: 0
 Community/Infosec Context: TRAP2, SNMP v2c, community public
 Uptime: 0
 Description: Cold Start
 PDU Attribute/Value Pair Array:
.iso.org.dod.internet.mgmt.mib-2.system.sysUpTime.sysUpTimeInstance = Timeticks: (853395100) 98 days, 18:32:31.00
.iso.org.dod.internet.snmpV2.snmpModules.snmpMIB.snmpMIBObjects.snmpTrap.snmpTrapOID.0 = OID: .iso.org.dod.internet.private.enterprises.snmpNotifier.snmpNotifierDefaultTrap
.iso.org.dod.internet.private.enterprises.snmpNotifier.snmpNotifierAlertsObjects.snmpNotifierAlertId = STRING: "1.3.6.1.4.1.98789[environment=production,label=test]"
.iso.org.dod.internet.private.enterprises.snmpNotifier.snmpNotifierAlertsObjects.snmpNotifierAlertSeverity = STRING: "critical"
.iso.org.dod.internet.private.enterprises.snmpNotifier.snmpNotifierAlertsObjects.snmpNotifierAlertDescription = STRING: "2/3 告警正在触发:

状态: critical
- 告警: TestAlert
  摘要: this is the summary
  描述: this is the description on job1

状态: warning
- 告警: TestAlert
  摘要: this is the random summary
  描述: this is the description of alert 1"
 --------------

使用用户自定义对象

可通过 --trap.user-object 参数添加额外字段。

例如，使用模板 {{ len .Alerts }} 告警正在触发。 并通过 --trap.user-object=4=alert-count.tpl 参数指定，将生成：

console
$ snmptrapd -m ALL -m +SNMP-NOTIFIER-MIB -f -Of -Lo -c scripts/snmptrapd.conf
 Agent Address: 0.0.0.0
 Agent Hostname: localhost
 Date: 1 - 0 - 0 - 1 - 1 - 1970
 Enterprise OID: .
 Trap Type: Cold Start
 Trap Sub-Type: 0
 Community/Infosec Context: TRAP2, SNMP v2c, community public
 Uptime: 0
 Description: Cold Start
 PDU Attribute/Value Pair Array:
.iso.org.dod.internet.mgmt.mib-2.system.sysUpTime.sysUpTimeInstance = Timeticks: (2665700) 7:24:17.00
.iso.org.dod.internet.snmpV2.snmpModules.snmpMIB.snmpMIBObjects.snmpTrap.snmpTrapOID.0 = OID: .iso.org.dod.internet.private.enterprises.snmpNotifier.snmpNotifierDefaultTrap
.iso.org.dod.internet.private.enterprises.snmpNotifier.snmpNotifierAlertsObjects.snmpNotifierAlertId = STRING: "1.3.6.1.4.1.98789[environment=production,label=test]"
.iso.org.dod.internet.private.enterprises.snmpNotifier.snmpNotifierAlertsObjects.snmpNotifierAlertSeverity = STRING: "critical"
.iso.org.dod.internet.private.enterprises.snmpNotifier.snmpNotifierAlertsObjects.snmpNotifierAlertDescription = STRING: "2/3 告警正在触发:

状态: critical
- 告警: TestAlert
  摘要: this is the summary
  描述: this is the description on job1

状态: warning
- 告警: TestAlert
  摘要: this is the random summary
  描述: this is the description of alert 1"
.iso.org.dod.internet.private.enterprises.snmpNotifier.snmpNotifierAlertsUserObjects.4 = STRING: "2 告警正在触发。"
--------------

模板使用

陷阱描述模板支持任何 Go 模板指令。用户可通过 --trap.description-template 参数指定自定义模板文件来自定义陷阱描述格式。

同样，用户对象模板也支持 Go 模板语法，可用于创建自定义的 SNMP 对象输出。