SNMP Notifier Integration Guide

Version 1.6.8 | Updated: July 24, 2026

SNMP Notifier Integration Guide

This document describes how Alertmanager sends SNMP traps to external Network Management Systems (NMS) using snmp-notifier.

1. Architecture
2. Configuration
3. SNMP Versions
4. Custom OIDs
5. MIB File
6. Templates
7. Testing
8. Troubleshooting

1. Architecture

Data Flow

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Prometheus    │────▶│  Alertmanager   │────▶│  snmp-notifier  │────▶│   NMS/Zabbix    │
│  (alert rules)  │     │    (webhook)    │     │   (UDP trap)    │     │   (port 162)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │                       │
   prometheus_rules.yml    POST JSON             SNMP v2c/v3 trap         Receives &
   fires alert             to :9464              to destination           processes

Components

Component	Port	Description
Alertmanager	9093	Routes alerts to snmp-notifier via webhook
snmp-notifier	9464	Converts JSON alerts to SNMP traps
NMS	162	Receives SNMP traps (Zabbix, Nagios, etc.)
snmp-catcher	8089	Test receiver with Web UI (optional)

Component

Port

Description

Alertmanager

9093

Routes alerts to snmp-notifier via webhook

snmp-notifier

9464

Converts JSON alerts to SNMP traps

NMS

162

Receives SNMP traps (Zabbix, Nagios, etc.)

snmp-catcher

8089

Test receiver with Web UI (optional)

Docker Services

# 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: snmp-catcher:local
  ports: 162/udp, 8080 (Web UI)
  profiles: [snmp]

2. Configuration

Environment Variables (.env)

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

snmp-notifier Command Line Options

Option Default Description

Option	Default	Description
`--web.listen-address`	`127.0.0.1:9464`	Webhook listen address
`--snmp.destination`	`127.0.0.1:162`	NMS trap destination
`--snmp.version`	`V2c`	SNMP version (V2c or V3)
`--snmp.community`	`public`	SNMPv2c community string
`--snmp.timeout`	`5s`	Trap send timeout
`--snmp.retries`	`3`	Number of retry attempts
`--trap.default-oid`	-	Default OID for traps
`--trap.oid-label`	`oid`	Label containing custom OID
`--trap.description-template`	-	Go template for description

--web.listen-address

127.0.0.1:9464

Webhook listen address

--snmp.destination

127.0.0.1:162

NMS trap destination

--snmp.version

V2c

SNMP version (V2c or V3)

--snmp.community

public

SNMPv2c community string

--snmp.timeout

5s

Trap send timeout

--snmp.retries

3

Number of retry attempts

--trap.default-oid

Default OID for traps

--trap.oid-label

oid

Label containing custom OID

--trap.description-template

Go template for description

Alertmanager Webhook Configuration

The entrypoint.sh automatically adds snmp-notifier webhook:

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

3. SNMP Versions

SNMPv2c

Simple community-based authentication. Good for internal networks.

SNMP_VERSION=V2c
SNMP_COMMUNITY=public

Security: Community string sent in plaintext. Use only on trusted networks.

SNMPv3 (Recommended for Production)

Provides authentication and encryption.

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

Security Levels:

Level	Auth	Encryption	Variables
noAuthNoPriv	No	No	username only
authNoPriv	Yes	No	username + auth password
authPriv	Yes	Yes	username + auth + priv passwords

Level

Auth

Encryption

Variables

noAuthNoPriv

username only

authNoPriv

Yes

username + auth password

authPriv

Yes

username + auth + priv passwords

Supported Protocols:

Type	Options
Authentication	SHA (recommended), MD5
Privacy	AES (recommended), DES

Type

Options

Authentication

SHA (recommended), MD5

Privacy

AES (recommended), DES

4. Custom OIDs

Using Label in Alert Rules

Add oid label to Prometheus alert rules for custom trap OID:

# 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.99999.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.99999.2.0.50"   # Custom OID
        annotations:
          summary: "High CPU usage on {{ $labels.instance }}"

Default OID

If no oid label is present, snmp-notifier uses:

1.3.6.1.4.1.99999.2.0.99  (generic alert)

OID Structure

1.3.6.1.4.1.99999         Enterprise OID (placeholder)
           │
           └── .2.0.X     Trap definitions
                  │
                  ├── .1   AcsCommProblem
                  ├── .3   DbUnreachable
                  ├── .11  LicenseExpiring
                  ├── .21  DeviceAccessDenied
                  └── .99  Generic (default)

5. MIB File

Location

prometheus-grafana-stack/alertmanager/mibs/
├── FRIENDLY-TECH-ACS-MIB.txt    # MIB definition
└── OID-MAPPING.md               # OID reference

OID Categories

Infrastructure Alarms (.2.0.1 - .2.0.10)

Trap OID	Name	Alertmanager alertname	Severity
.2.0.1	ftAcsCommProblem	AcsCommProblem	critical
.2.0.2	ftAcsCommRestored	AcsCommProblem (resolved)	clear
.2.0.3	ftDbUnreachable	DbUnreachable	critical
.2.0.4	ftDbRestored	DbUnreachable (resolved)	clear
.2.0.5	ftTimeDrift	TimeDrift	warning
.2.0.6	ftTimeSynced	TimeDrift (resolved)	clear

Trap OID

Name

Alertmanager alertname

Severity

.2.0.1

ftAcsCommProblem

AcsCommProblem

critical

.2.0.2

ftAcsCommRestored

AcsCommProblem (resolved)

clear

.2.0.3

ftDbUnreachable

DbUnreachable

critical

.2.0.4

ftDbRestored

DbUnreachable (resolved)

clear

.2.0.5

ftTimeDrift

TimeDrift

warning

.2.0.6

ftTimeSynced

TimeDrift (resolved)

clear

Licensing Alarms (.2.0.11 - .2.0.20)

Trap OID	Name	Alertmanager alertname	Severity
.2.0.11	ftLicenseExpiring	LicenseExpiring	warning
.2.0.12	ftLicenseExpired	LicenseExpired	critical
.2.0.13	ftLicenseRenewed	LicenseExpired (resolved)	clear

Trap OID

Name

Alertmanager alertname

Severity

.2.0.11

ftLicenseExpiring

LicenseExpiring

warning

.2.0.12

ftLicenseExpired

LicenseExpired

critical

.2.0.13

ftLicenseRenewed

LicenseExpired (resolved)

clear

Device Limit Alarms (.2.0.21 - .2.0.40)

Trap OID	Name	Alertmanager alertname	Severity
.2.0.21	ftDeviceAccessDenied	DeviceAccessDenied	critical
.2.0.22	ftDeviceLimitWarning	DeviceLimitWarning	warning
.2.0.23	ftDeviceLimitExceeded	DeviceLimitExceeded	critical
.2.0.25	ftTR069LimitWarning	TR069LimitWarning	warning
.2.0.26	ftTR069LimitExceeded	TR069LimitExceeded	critical
.2.0.27	ftLWM2MLimitWarning	LWM2MLimitWarning	warning
.2.0.28	ftLWM2MLimitExceeded	LWM2MLimitExceeded	critical
.2.0.29	ftMQTTLimitWarning	MQTTLimitWarning	warning
.2.0.30	ftMQTTLimitExceeded	MQTTLimitExceeded	critical
.2.0.31	ftUSPLimitWarning	USPLimitWarning	warning
.2.0.32	ftUSPLimitExceeded	USPLimitExceeded	critical

Trap OID

Name

Alertmanager alertname

Severity

.2.0.21

ftDeviceAccessDenied

DeviceAccessDenied

critical

.2.0.22

ftDeviceLimitWarning

DeviceLimitWarning

warning

.2.0.23

ftDeviceLimitExceeded

DeviceLimitExceeded

critical

.2.0.25

ftTR069LimitWarning

TR069LimitWarning

warning

.2.0.26

ftTR069LimitExceeded

TR069LimitExceeded

critical

.2.0.27

ftLWM2MLimitWarning

LWM2MLimitWarning

warning

.2.0.28

ftLWM2MLimitExceeded

LWM2MLimitExceeded

critical

.2.0.29

ftMQTTLimitWarning

MQTTLimitWarning

warning

.2.0.30

ftMQTTLimitExceeded

MQTTLimitExceeded

critical

.2.0.31

ftUSPLimitWarning

USPLimitWarning

warning

.2.0.32

ftUSPLimitExceeded

USPLimitExceeded

critical

Infrastructure Resource Alarms (.2.0.41 - .2.0.70)

Trap OID	Name	Alertmanager alertname	Severity	Threshold
.2.0.41	ftServerDown	ServiceDown	critical	—
.2.0.43	ftAPIDown	APIDown	critical	—
.2.0.45	ftFrontendDown	FrontendDown	critical	—
.2.0.47	ftCPUUsageWarning	CPUUsageHigh	warning	>=80%
.2.0.48	ftCPUUsageCritical	CPUUsageCritical	critical	>=90%
.2.0.50	ftMemoryUsageWarning	MemoryUsageHigh	warning	>=80%
.2.0.51	ftMemoryUsageCritical	MemoryUsageCritical	critical	>=90%
.2.0.53	ftDiskSpaceWarning	DiskSpaceFilling	warning	>=80%
.2.0.54	ftDiskSpaceCritical	DiskSpaceCritical	critical	>=90%
.2.0.56	ftTCPSessionsWarning	TCPSessionsWarning	warning	>=800
.2.0.57	ftTCPSessionsCritical	TCPSessionsCritical	critical	>=1000
.2.0.59	ftHTTPSessionsWarning	HTTPSessionsWarning	warning	>=800
.2.0.60	ftHTTPSessionsCritical	HTTPSessionsCritical	critical	>=1000
.2.0.62	ftUDPSessionsWarning	UDPSessionsWarning	warning	>=800
.2.0.63	ftUDPSessionsCritical	UDPSessionsCritical	critical	>=1000
.2.0.65	ftHazelcastNodeDown	HazelcastNodeDown	critical	—
.2.0.67	ftMySQLDown	MySQLDown	critical	—

Trap OID

Name

Alertmanager alertname

Severity

Threshold

.2.0.41

ftServerDown

ServiceDown

critical

—

.2.0.43

ftAPIDown

APIDown

critical

—

.2.0.45

ftFrontendDown

FrontendDown

critical

—

.2.0.47

ftCPUUsageWarning

CPUUsageHigh

warning

>=80%

.2.0.48

ftCPUUsageCritical

CPUUsageCritical

critical

>=90%

.2.0.50

ftMemoryUsageWarning

MemoryUsageHigh

warning

>=80%

.2.0.51

ftMemoryUsageCritical

MemoryUsageCritical

critical

>=90%

.2.0.53

ftDiskSpaceWarning

DiskSpaceFilling

warning

>=80%

.2.0.54

ftDiskSpaceCritical

DiskSpaceCritical

critical

>=90%

.2.0.56

ftTCPSessionsWarning

TCPSessionsWarning

warning

>=800

.2.0.57

ftTCPSessionsCritical

TCPSessionsCritical

critical

>=1000

.2.0.59

ftHTTPSessionsWarning

HTTPSessionsWarning

warning

>=800

.2.0.60

ftHTTPSessionsCritical

HTTPSessionsCritical

critical

>=1000

.2.0.62

ftUDPSessionsWarning

UDPSessionsWarning

warning

>=800

.2.0.63

ftUDPSessionsCritical

UDPSessionsCritical

critical

>=1000

.2.0.65

ftHazelcastNodeDown

HazelcastNodeDown

critical

—

.2.0.67

ftMySQLDown

MySQLDown

critical

—

Variable Bindings

OID Suffix	Name	Type	Description
.1.1.1	ftAlarmSeverity	INTEGER	1=critical, 2=warning, 3=info, 4=clear
.1.1.2	ftAlarmName	STRING	Alert name (e.g., “DbUnreachable”)
.1.1.3	ftAlarmSummary	STRING	Brief summary
.1.1.4	ftAlarmDescription	STRING	Detailed description
.1.1.5	ftAlarmInstance	STRING	Instance (server, host)
.1.1.6	ftAlarmTimestamp	STRING	ISO 8601 timestamp

OID Suffix

Name

Type

Description

.1.1.1

ftAlarmSeverity

INTEGER

1=critical, 2=warning, 3=info, 4=clear

.1.1.2

ftAlarmName

STRING

Alert name (e.g., “DbUnreachable”)

.1.1.3

ftAlarmSummary

STRING

Brief summary

.1.1.4

ftAlarmDescription

STRING

Detailed description

.1.1.5

ftAlarmInstance

STRING

Instance (server, host)

.1.1.6

ftAlarmTimestamp

STRING

ISO 8601 timestamp

Installing MIB on NMS

# 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

6. Templates

Description Template

Location: alertmanager/snmp-notifier-template.tmpl

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

Output Example:

[firing] DbUnreachable @ mysql-primary: Database connection failed

Available Template Variables

Variable Description

Variable	Description
`.Alerts`	Array of alerts
`.Status`	“firing” or “resolved”
`.Labels.alertname`	Alert name
`.Labels.severity`	Alert severity
`.Labels.instance`	Instance label
`.Annotations.summary`	Alert summary
`.Annotations.description`	Alert description
`.StartsAt`	Alert start time
`.EndsAt`	Alert end time (if resolved)

.Alerts

Array of alerts

.Status

“firing” or “resolved”

.Labels.alertname

Alert name

.Labels.severity

Alert severity

.Labels.instance

Instance label

.Annotations.summary

Alert summary

.Annotations.description

Alert description

.StartsAt

Alert start time

.EndsAt

Alert end time (if resolved)

Custom Template Example

{{- /* 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 -}}

7. Testing

Using SNMP Trap Catcher (Recommended)

Bootstrap offers built-in testing with SNMP Trap Catcher:

# During bootstrap, select option 2 for SNMP:
# "Use SNMP Trap Catcher for testing"

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

Features:

Real-time trap display
SNMPv2c and SNMPv3 support
Persistent storage (survives restarts)
Clear button to reset

Manual Testing

1. Check Services Running

docker ps | grep -E "snmp-notifier|snmp-catcher"

2. Send Test Alert

curl -X POST http://localhost:9093/api/v2/alerts \
  -H "Content-Type: application/json" \
  -d '[{
    "labels": {
      "alertname": "TestSNMPAlert",
      "severity": "warning",
      "oid": "1.3.6.1.4.1.99999.2.0.99"
    },
    "annotations": {
      "summary": "Test SNMP trap from CLI"
    }
  }]'

3. Check snmp-notifier Logs

docker logs snmp-notifier --tail 20

4. View Traps (if using snmp-catcher)

curl http://localhost:8080/health
# {"status":"ok","total_received":5,"traps_count":5}

Testing with snmptrap Command

# Send test trap directly (bypassing Alertmanager)
snmptrap -v 2c -c public localhost:162 '' \
  1.3.6.1.4.1.99999.2.0.3 \
  1.3.6.1.4.1.99999.1.1.1 i 1 \
  1.3.6.1.4.1.99999.1.1.2 s "DbUnreachable" \
  1.3.6.1.4.1.99999.1.1.3 s "Database server unreachable"

Testing SNMPv3

# 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.99999.2.0.3 \
  1.3.6.1.4.1.99999.1.1.2 s "TestV3"

8. Troubleshooting

Common Issues

Traps Not Received

Check snmp-notifier is running:

docker ps | grep snmp-notifier
docker logs snmp-notifier

Check firewall allows UDP 162:

# On NMS server
sudo tcpdump -i any udp port 162

Verify destination is correct:

grep SNMP_TRAP_ADDRESS .env
# Should show your NMS address

SNMPv3 Authentication Failed

Check credentials match NMS configuration:

grep -E "SNMP_AUTH|SNMP_PRIV" .env

Verify protocol compatibility:
- Some NMS only support SHA, not SHA-256
- Some only support AES-128, not AES-256
Check snmp-notifier logs for auth errors:

docker logs snmp-notifier 2>&1 | grep -i auth

Wrong OID in Trap

Check alert has oid label:

labels:
  oid: "1.3.6.1.4.1.99999.2.0.3"

If no label, default OID is used:

1.3.6.1.4.1.99999.2.0.99

Empty Description

Check template file exists:

docker exec snmp-notifier ls -la /etc/snmp-notifier/

Verify template syntax:

cat alertmanager/snmp-notifier-template.tmpl

Useful Commands

# 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"
  }]'

SNMP Notifier Integration Guide