SNMP Trap Receiver

Sentinel's SNMP trap receiver captures link state changes, authentication failures, and vendor-specific traps from network devices — no SNMP polling overhead required.

Supported Versions

  • SNMPv1 — legacy trap PDU (0xA4) with generic trap numbers and enterprise OIDs
  • SNMPv2c — modern trap PDU (0xA7) with sysUpTime + snmpTrapOID conventions
  • SNMPv2c INFORM — PDU 0xA6; decoded the same way

SNMPv3 is not currently supported

SNMPv3 requires USM (User Security Model) with HMAC authentication and optional encryption. If you need v3, please let us know — it's on the roadmap.

Well-Known Trap Mapping

Standard SNMPv2-MIB trap OIDs are automatically mapped to human-readable event names with appropriate severities:

1.3.6.1.6.3.1.1.5.1  coldStart                Low
1.3.6.1.6.3.1.1.5.2  warmStart                Info
1.3.6.1.6.3.1.1.5.3  linkDown                 Medium
1.3.6.1.6.3.1.1.5.4  linkUp                   Info
1.3.6.1.6.3.1.1.5.5  authenticationFailure    High
1.3.6.1.6.3.1.1.5.6  egpNeighborLoss          Medium

Enterprise-specific OIDs (anything outside the well-known set) pass through with the full OID as the event type and all varbinds preserved in the raw event.

Configuring UniFi Devices to Send Traps

UniFi switches and gateways support outbound SNMP traps via the controller UI:

UniFi Controller → Settings → System 
SNMP Community:     public (or custom — match your filter below)
Trap Destination:   <your-sentinel-host>
Trap Port:          1162  (or 162 if your host runs privileged)
Trap Version:       v2c

Why port 1162 and not 162?

The standard SNMP trap port is UDP 162, but binding to ports below 1024 requires root. Sentinel listens on unprivileged 1162 by default. If you need standard port 162, add a CAP_NET_BIND_SERVICE capability to the binary or use iptables to redirect 162 → 1162.

Enabling the Collector

config/local.toml 
[snmp_trap]
enabled = true
listen_addr = "0.0.0.0"
listen_port = 1162
# Optional: filter by community string. Traps with a non-matching community are dropped.
community = "public"

Where Traps Appear

Decoded traps flow through the standard event pipeline:

  • Event class: network
  • Category: device
  • Tags: snmp-trap, snmp-v1 or snmp-v2c
  • Device IP: agent_addr (v1) or source IP of the packet (v2c)

Filter in the Network Events page with the "SNMP" chip or query ?tag=snmp-trap via the Events API.

Example Decoded Trap

Decoded SNMPv2c linkUp 
{
  "event_type": "snmp_1.3.6.1.6.3.1.1.5.4",
  "event_name": "linkUp",
  "event_class": "network",
  "category": "device",
  "severity": "info",
  "device_ip": "192.168.1.1",
  "raw_event": {
    "trap_oid": "1.3.6.1.6.3.1.1.5.4",
    "community": "public",
    "version": "v2c",
    "varbinds": [
      {"oid": "1.3.6.1.2.1.1.3.0", "value": "12345"},
      {"oid": "1.3.6.1.6.3.1.1.4.1.0", "value": "1.3.6.1.6.3.1.1.5.4"}
    ]
  }
}

Testing

Send a synthetic v2c trap from any Linux host with snmptrap:

snmptrap -v 2c -c public <sentinel-host>:1162 '' \
  1.3.6.1.6.3.1.1.5.4 \
  1.3.6.1.2.1.2.2.1.1.1 i 1

Expect a linkUp event in the Network Events view within a second.