Skip to content

SNMP.md

Latest commit

 

History

History
116 lines (87 loc) · 5.77 KB

SNMP.md

File metadata and controls

116 lines (87 loc) · 5.77 KB
Raw

SNMP monitoring, traps & inventory sync

Rackpad can poll devices over SNMP, receive SNMP traps, reflect interface link-state, and (optionally) sync VLANs and subnets from network gear into IPAM.

This is the operator/admin guide. For implementation status, phase tracking, and the outstanding backlog, see SNMP_IMPLEMENTATION_PLAN.md.

What you get

  • SNMP monitors (v1 / v2c / v3) alongside ICMP / TCP / HTTP / HTTPS checks
  • IF-MIB interface monitoring — per-port link state, with ifHighSpeed used to fill in a port's speed when it's blank
  • SNMP-verified badges in Ports, the Dashboard, and the Visualizer
  • Trap receiver (v1 / v2c) for linkUp / linkDown with device auto-learn
  • Inventory sync (opt-in) — preview/apply VLANs and subnets from a device into IPAM; DHCP scopes are preview-only for now

Quick start (v2c)

  1. Make sure the device has SNMP enabled with a read-only community string.
  2. In Rackpad, open Monitoring (or a device's Monitoring tab) and add a monitor of type SNMP.
  3. Choose version v2c, enter the community string and the OID to check (e.g. an ifOperStatus OID for a port), pick a match mode, and save.
  4. Run the check. The result and any linked port's link-state update on success.

SNMP versions

v1 / v2c

A read-only community string per monitor. Simple; the community travels in cleartext, so keep SNMP on a trusted management network.

v3 (recommended on shared networks)

SNMPv3 adds auth + privacy. Credentials are stored per lab, encrypted at rest (AES-256-GCM):

  1. Set RACKPAD_SECRET_KEY before storing any v3 credential (see env table). Generate one with openssl rand -hex 32. Without it, saving v3 credentials fails — v1/v2c and the other monitor types still work.
  2. Open a device's Monitoring / SNMP area and add SNMPv3 credentials (security name, auth protocol + key, privacy protocol + key).
  3. Create an SNMP monitor that uses v3.

Rotating RACKPAD_SECRET_KEY invalidates stored v3 secrets — re-enter them after a key change.

Interface monitoring & port link-state

An SNMP monitor can be linked to a specific port via its ifIndex. When linked, poll results (and matching traps) drive the port's link-state badge across Ports, the Dashboard, and the Visualizer. Discover/import reads IF-MIB so a port's speed can be auto-filled from ifHighSpeed when it isn't set manually.

Traps

Rackpad runs a UDP trap receiver at startup.

  • Default port: 1162 (unprivileged on purpose, so containers don't need extra capabilities). Forward your network's standard 162 → 1162 upstream, or point agents directly at 1162.
  • Docker: publish the port, e.g. -p 1162:1162/udp (or use host networking).
  • Incoming v1/v2c linkUp/linkDown traps update the matching monitor/port; an unknown source IP is auto-learned to a device when possible. Duplicate traps are de-duplicated within ~30s.
  • SNMPv3 linkUp/linkDown traps are supported for authenticated and encrypted USM credentials. Map the trap source, device, or SNMP monitor to the matching lab credential so Rackpad can validate and decrypt the packet.

Configure with SNMP_TRAP_ENABLED, SNMP_TRAP_PORT, SNMP_TRAP_BIND (see table). Receiver status is reported on /api/health and /api/snmp-traps/status.

Inventory sync (preview / apply)

Off by default. Set SNMP_INVENTORY_SYNC=1 to enable it, then use the SNMP sync panel on a device's detail page to preview a diff and apply it.

  • Applies: VLANs and subnets read from the device (Q-BRIDGE VLANs, IP-MIB subnets) into the active lab's IPAM.
  • Preview only: DHCP scopes (apply is on the roadmap).
  • Safety: sync is a merge/mirror that never silently deletes existing assignments — review the preview before applying.
  • Profiles: a generic profile set ships today (Q-BRIDGE VLANs + IP-MIB subnets). Vendor-specific profiles (pfSense/OPNsense, UniFi, …) are not in yet.

Environment variables

Variable Default Purpose
RACKPAD_SECRET_KEY (unset) Encrypts SNMPv3 credential secrets. Required only to store v3 credentials. Use a long random value (openssl rand -hex 32).
SNMP_INVENTORY_SYNC 0 Set 1 to enable VLAN/subnet sync (DHCP preview-only).
SNMP_TRAP_ENABLED 1 Enable/disable the trap receiver.
SNMP_TRAP_PORT 1162 UDP port the trap receiver binds.
SNMP_TRAP_BIND 0.0.0.0 Interface the trap receiver binds to.

Security notes

  • Keep SNMP on a trusted management network; prefer v3 where possible.
  • Treat community strings as secrets — they are read-only but still grant device visibility.
  • Store RACKPAD_SECRET_KEY outside the repo (env / secrets manager); back it up, since losing it makes stored v3 secrets unreadable.

Current limitations

Not yet available (tracked in the implementation plan → Outstanding work):

  • pfSense/OPNsense and other vendor-specific profiles
  • DHCP scope sync apply (preview only today)
  • Scheduled/automatic sync
  • SNMPv3 traps
  • regex SNMP match mode