SNMP Notifier Integration Guide

# snmp-notifier - production trap sender
snmp-notifier:
  image: maxwo/snmp-notifier:v2.1.0
  ports: 9464 (internal)
  profiles: [snmp]

# snmp-catcher - testing trap receiver
snmp-catcher:
  image: hub.friendly-tech.com/monitoring/snmp-catcher:1.6.9
  ports: 162/udp, 8089 (Web UI)
  profiles: [snmp]

# ============================================
# SNMP Trap Notifications
# ============================================

# Destination NMS address
SNMP_TRAP_ADDRESS=nms.company.com:162

# SNMP Version: V2c or V3
SNMP_VERSION=V2c

# SNMPv2c settings
SNMP_COMMUNITY=public

# SNMPv3 settings (when SNMP_VERSION=V3)
SNMP_AUTH_USERNAME=snmpuser
SNMP_AUTH_PASSWORD=authpassword
SNMP_PRIV_PASSWORD=privpassword
SNMP_AUTH_PROTOCOL=SHA      # SHA or MD5
SNMP_PRIV_PROTOCOL=AES      # AES or DES

receivers:
  - name: 'default'
    webhook_configs:
      - url: 'http://127.0.0.1:9464/alerts'
        send_resolved: true

SNMP_VERSION=V2c
SNMP_COMMUNITY=public

SNMP_VERSION=V3
SNMP_AUTH_USERNAME=snmpuser
SNMP_AUTH_PASSWORD=authpassword123
SNMP_PRIV_PASSWORD=privpassword456
SNMP_AUTH_PROTOCOL=SHA
SNMP_PRIV_PROTOCOL=AES

# prometheus_rules.yml
groups:
  - name: infrastructure
    rules:
      - alert: DbUnreachable
        expr: up{job="mysql"} == 0
        for: 1m
        labels:
          severity: critical
          oid: "1.3.6.1.4.1.65666.2.0.3"    # Custom OID
        annotations:
          summary: "Database {{ $labels.instance }} is unreachable"
          description: "MySQL server has been down for more than 1 minute"

      - alert: HighCpuUsage
        expr: node_cpu_usage > 90
        for: 5m
        labels:
          severity: warning
          oid: "1.3.6.1.4.1.65666.2.0.50"   # Custom OID
        annotations:
          summary: "High CPU usage on {{ $labels.instance }}"

labels:
  severity: critical
  oid:          "1.3.6.1.4.1.65666.2.0.41"   # sent while firing
  oid_resolved: "1.3.6.1.4.1.65666.2.0.42"   # sent when it clears

--trap.default-objects-base-oid=1.3.6.1.4.1.65666.1.1   # .1 oid, .2 severity, .3 description
--trap.user-objects-base-oid=1.3.6.1.4.1.65666.1.1      # .4 instance, .5 name, .6 summary, .7 timestamp
--alert.severity-label=severity
--trap.description-template=/etc/snmp-notifier/description.tmpl
--trap.user-object=4=/etc/snmp-notifier/objects/instance.tmpl
--trap.user-object=5=/etc/snmp-notifier/objects/name.tmpl
--trap.user-object=6=/etc/snmp-notifier/objects/summary.tmpl
--trap.user-object=7=/etc/snmp-notifier/objects/timestamp.tmpl

# Copy MIB file to NMS
scp alertmanager/mibs/FRIENDLY-TECH-ACS-MIB.txt nms:/usr/share/snmp/mibs/

# Verify MIB is readable
snmptranslate -m +FRIENDLY-TECH-ACS-MIB -IR ftDbUnreachable
# Expected: FRIENDLY-TECH-ACS-MIB::ftDbUnreachable

{{- /* SNMP Notifier Description Template */ -}}
{{ range .Alerts -}}
[{{ .Status }}] {{ .Labels.alertname }}{{ if .Labels.instance }} @ {{ .Labels.instance }}{{ end }}{{ if .Annotations.summary }}: {{ .Annotations.summary }}{{ end }}
{{ end -}}

{{- /* Custom template with severity and timestamp */ -}}
{{ range .Alerts -}}
ALERT: {{ .Labels.alertname }}
SEVERITY: {{ .Labels.severity | toUpper }}
INSTANCE: {{ .Labels.instance | default "N/A" }}
STATUS: {{ .Status }}
TIME: {{ .StartsAt.Format "2006-01-02 15:04:05" }}
{{ if .Annotations.summary -}}
SUMMARY: {{ .Annotations.summary }}
{{ end -}}
{{ if .Annotations.description -}}
DESCRIPTION: {{ .Annotations.description }}
{{ end -}}
---
{{ end -}}

# In the bootstrap config menu:
#   Configuration › Alerting › SNMP › "Built-in Trap Catcher (testing)"

# Web UI available at:
http://<server>:8089

# Send test trap directly (bypassing Alertmanager).
# snmpTrapOID.0 = per-alert trap OID (.2.0.3 = ftDbUnreachable), then the 7
# varbinds in wire order. NOTE: severity (.2) is a STRING, not an integer.
snmptrap -v 2c -c public localhost:162 '' \
  1.3.6.1.4.1.65666.2.0.3 \
  1.3.6.1.4.1.65666.1.1.1 s "1.3.6.1.4.1.65666.2.0.3[alertname=DbUnreachable]" \
  1.3.6.1.4.1.65666.1.1.2 s "critical" \
  1.3.6.1.4.1.65666.1.1.3 s "[firing] DbUnreachable @ db-1: DB unreachable" \
  1.3.6.1.4.1.65666.1.1.4 s "db-1:9104" \
  1.3.6.1.4.1.65666.1.1.5 s "DbUnreachable" \
  1.3.6.1.4.1.65666.1.1.6 s "Database server unreachable" \
  1.3.6.1.4.1.65666.1.1.7 s "2026-07-25T14:03:11Z"

# SHA/AES
snmptrap -v 3 -u snmpuser -l authPriv \
  -a SHA -A authpassword \
  -x AES -X privpassword \
  localhost:162 '' \
  1.3.6.1.4.1.65666.2.0.3 \
  1.3.6.1.4.1.65666.1.1.2 s "TestV3"

# Restart snmp-notifier
docker compose restart snmp-notifier

# View real-time logs
docker logs -f snmp-notifier

# Check Alertmanager config
curl -s http://localhost:9093/api/v2/status | jq '.config'

# List active alerts
curl -s http://localhost:9093/api/v2/alerts | jq '.[].labels.alertname'

# Resolve test alert
curl -X POST http://localhost:9093/api/v2/alerts \
  -H "Content-Type: application/json" \
  -d '[{
    "labels": {"alertname": "TestSNMPAlert", "severity": "warning"},
    "endsAt": "2024-01-01T00:00:00Z"
  }]'