Skip to content

SNMP_IMPLEMENTATION_PLAN.md

Latest commit

 

History

History
439 lines (307 loc) · 19 KB

SNMP_IMPLEMENTATION_PLAN.md

File metadata and controls

439 lines (307 loc) · 19 KB
Raw

SNMP Monitoring — Full Implementation Plan

Tracks GitHub issue #35 and related monitoring/inventory requests.

Last updated: 2026-06-11
Current baseline: Rackpad 1.6.2 beta — SNMP Phases 1–5 (v1) implemented plus authenticated/encrypted SNMPv3 traps (schema v23). Enable inventory sync with SNMP_INVENTORY_SYNC=1.

Shipped in 1.6.x (Phases 1–5 v1)

Phase Theme Schema / key paths
1 IF-MIB monitors, port linkage, match modes, OID presets v21 — server/lib/snmp-match.ts, monitoring.ts
2 SNMPv3 + per-lab encrypted credentials v22 — server/lib/snmp-v3.ts, snmp-credentials.ts
3 Trap receiver, trap log, linkUp/Down actions v23 — server/lib/snmp-traps.ts, snmp-trap-parser.ts
4 Port/dashboard/visualizer SNMP verified state — src/lib/snmp-port-status.ts, port components
5 v1 Profile framework + VLAN/subnet sync preview/apply — server/lib/snmp-profiles/, server/lib/snmp-sync.ts

Automated tests: 66 server tests passing (incl. SNMP match, traps, sync diff, credentials).

Current State (as of 1.6.2 beta)

Area Status Notes
SNMP GET (v1/v2c/v3) Done server/lib/snmp.ts, snmp-v3.ts
Monitor type snmp + match modes Done any, equals, notEquals, in (no regex yet)
IF-MIB discover / import Done ifHighSpeed → port speed when empty; port match preview
Monitor ↔ port linkage Done portId, snmpIfIndex; syncMonitorPortState()
Port linkState from SNMP Done Poll + trap path; badges in Ports/Dashboard/Visualizer
SNMPv3 + credentials Done Per-lab AES-256-GCM secrets; RACKPAD_SECRET_KEY
SNMP traps (UDP) Done Default 1162; env SNMP_TRAP_*; v1/v2c/v3 link traps
Trap → monitor / port / alert Done Dedupe 30s; auto-learn IP→device
Inventory sync (VLAN/subnet) Done (v1) Feature flag SNMP_INVENTORY_SYNC=1; merge + mirror
Vendor profiles (generic) Done Q-BRIDGE VLANs, IP-MIB subnets, combined profile
Vendor profiles (pfSense/UniFi/…) Not started Deferred per product decision
DHCP scope sync apply Not started Preview message only in v1
Scheduled SNMP / sync cron Not started Phase 5.3
Phase 6 (Inform, Prometheus, …) Not started See below

Outstanding work

Prioritized backlog. Track here until shipped + documented.

P0 — Close Phase 5 exit criteria & release prep

Item Phase Notes
pfSense / OPNsense profile 5.1 Host MIBs for subnets + DHCP scope preview; first vendor-specific profile
DHCP scope merge apply 5.2 Add missing scopes only; never silent delete assignments
README/admin guide follow-up Docs Add more trap forwarding examples (pfSense, UniFi, managed switches)
Update #35 / issue map Docs Mark 1.6.x shipped scope vs remaining vendor sync
Manual lab matrix Test Linux snmpd, one managed switch, pfSense — preview/apply + traps

P1 — Phase 5 remainder

Item Notes
Scheduled sync per device Optional interval (e.g. daily merge) on Monitoring or device row
Q-BRIDGE port ↔ VLAN membership Bridge MIB walk; port allowedVlanIds preview (high value for switches)
Subnet ↔ VLAN linking on sync Tie ipAdEnt subnets to Q-BRIDGE VLAN when both profiles run
Mirror policy UX Lab-level sync history / last preview snapshot (optional)

P2 — Phase 4 / monitoring polish

Item Notes
Bridge MIB / MAU for SFP status Phase 4.3 — devices that expose optics OIDs
snmpMatchMode: regex Phase 1.1 — was spec’d, not implemented
Structured SNMP poll logging Phase 1.4 — timeout/auth failure log lines
Bulk “Add SNMP interface monitors” Multi-device discover/import from Devices list

P3 — Phase 6 (enterprise & scale)

Item Notes
SNMP Inform ack Reliable traps
Bulk polling queue + concurrency limit Avoid N simultaneous walks
Per-lab SNMP rate limits Protect agents and Rackpad
Prometheus metrics Poll latency, trap rate, failures
i18n for SNMP UI Monitoring, sync panel, trap log, credentials

P4 — Documentation (still open)

  • README: full SNMP setup (community, firewall, Docker -p 1162:1162/udp, host networking)
  • Admin guide: trap forwarding examples (pfSense, UniFi)
  • OID cookbook: homelab IF-MIB examples
  • Docker Compose example env block for all SNMP_* + RACKPAD_SECRET_KEY

Explicitly deferred (product decisions)

  • pfSense/Q-BRIDGE port membership in first sync sprint — VLAN names + subnets first ✅ done; port VLAN tagging later
  • UniFi / MikroTik / FortiGate profiles — one at a time after pfSense
  • YAML/community-contributed profiles in repo — evaluate after first vendor profile ships
  • Silent deletes in IPAM sync — blocked; mirror requires allowDeletes + dependency checks ✅

Resolved decisions (2026-06)

# Decision Resolution
1 Credentials scope Per lab (+ optional per device / per monitor override)
2 Trap port default 1162 in Docker; document host 162 → container 1162
3 First vendor profile Generic Q-BRIDGE + IP-MIB shipped; pfSense next
4 Sync scope v1 VLANs + subnets apply; DHCP preview only (apply outstanding)
5 Profile contribution model TypeScript profiles in repo for now; YAML/UI TBD

Recommended next sprint

  1. pfSense/OPNsense profile — subnets + DHCP scope preview.
  2. DHCP merge apply — add missing scopes only.
  3. README + CHANGELOG — ship-ready docs for SNMP bundle.
  4. Manual validation on real gear; then tag 2.0.0 candidate.

(Do not push/release until reviewed — work stays on dev.)

Vision

Rackpad should support SNMP as a first-class monitoring and (optionally) inventory source:

  1. Poll device and interface health via standard and vendor OIDs.
  2. Receive traps for near-real-time link/device events.
  3. Authenticate with SNMPv3 where v2c is insufficient.
  4. Link SNMP interfaces to Rackpad ports/devices.
  5. Sync (optional, profile-driven) VLAN/IPAM data from capable devices.

Current State (legacy checklist — see tables above)

Note: The table at the top of this document is authoritative. Phase sections below retain historical task lists; items not marked [x] may still be outstanding — see Outstanding work.

Architecture Target

flowchart TB
  subgraph rackpad [Rackpad Server]
    Poll[Scheduled SNMP Poll Loop]
    Trap[SNMP Trap Receiver :162]
    Profiles[Vendor OID Profiles]
    Engine[Sync Engine]
    DB[(SQLite)]
  end

  subgraph ui [Client]
    MonUI[Monitoring / Device Detail]
    SyncUI[SNMP Sync Admin]
    AlertUI[Alerts]
  end

  Devices[Network Devices SNMP Agents]

  Devices -->|GET/GET-NEXT/WALK| Poll
  Devices -->|TRAP/INFORM| Trap
  Poll --> DB
  Trap --> DB
  Profiles --> Engine
  Poll --> Engine
  Engine --> DB
  DB --> MonUI
  DB --> SyncUI
  DB --> AlertUI
  Poll --> AlertUI
  Trap --> AlertUI
Loading

Design principles

  • Keep SNMP protocol code in server/lib/snmp*.ts (no scattered BER logic).
  • Treat IF-MIB as the universal layer; vendor features as profiles.
  • Never auto-write VLAN/IPAM without explicit admin opt-in + dry-run preview.
  • All SNMP operations run from the Rackpad server/container (same as ICMP today).
  • Respect per-lab ACLs on every new route and sync job.

Phase 1 — Hardening & polish ✅ (dev)

Goal: Make existing SNMP polling production-ready before adding traps/v3.

1.1 Monitor model extensions

  • Add portId (nullable FK → ports.id) on deviceMonitors.
  • Add snmpIfIndex (nullable integer) for traceability.
  • Add snmpMatchMode: any | equals | notEquals | in ( regex outstanding ).
  • Migration + backup/restore in server/routes/admin.ts.

1.2 Match logic

  • Extend snmpCheck() to support equals, in, any, notEquals.
  • Map IF-MIB operStatus integers to human labels in UI and audit log.

1.3 UI improvements

  • OID presets dropdown: sysUpTime, ifOperStatus, ifAdminStatus, ifHighSpeed.
  • Link imported interface monitors to Rackpad ports by name/ifIndex heuristic.
  • Monitoring page: bulk-run respects lab ACL.
  • Fix canManageMonitoring → use per-lab editor (not admin-only) for monitor CRUD.

1.4 Observability

  • Structured log lines for SNMP timeout / error status / auth failure. Outstanding
  • Audit events: monitor.snmp.discover, monitor.snmp.import.

1.5 Tests

  • Unit tests for match modes, trap parser, sync diff, credentials.
  • Integration tests: SNMP responder, trap handling, sync apply (app.test.ts).

Exit criteria: ✅ Met on dev.

Phase 2 — SNMPv3 ✅ (dev)

Goal: Answer #35 comment: support v3 for devices that disable v2c.

2.1 Credentials model

  • Table snmpCredentials + devices.snmpCredentialId / monitor override.

2.2 Security

  • Encrypt SNMP secrets at rest (server/lib/secret-crypto.ts, RACKPAD_SECRET_KEY).
  • Never return passwords in API GET; mask in UI.
  • Document RACKPAD_SECRET_KEY in README.

2.3 Protocol

  • USM v3 in server/lib/snmp-v3.ts (pure JS).
  • authNoPriv and authPriv (MD5/SHA + AES128).

2.4 UI

  • Device / monitor forms: credential picker.
  • “Test SNMP” on credentials panel → GET via credential.

Exit criteria: ✅ Met on dev.

Phase 3 — SNMP traps ✅ (dev, v1/v2c/v3)

Goal: Real-time link/device events; issue title “traps”.

3.1 Trap receiver

  • UDP listener — default 1162 (SNMP_TRAP_PORT).
  • Env: SNMP_TRAP_ENABLED, SNMP_TRAP_PORT, SNMP_TRAP_BIND.
  • Parse SNMPv1/v2c traps.
  • Parse authenticated SNMPv3 traps.
  • Parse authenticated + encrypted SNMPv3 traps.
  • Dedupe window (30s).

3.2 Trap → inventory mapping

  • Tables snmpTrapSources, snmpTrapLog.
  • Auto-learn source IP → device via managementIp.
  • linkUp/linkDown OID handling.

3.3 Actions on trap

  • Update monitors via recordMonitorResult().
  • Set port linkState when monitor has portId / snmpIfIndex.
  • Alert pipeline + audit log.
  • Trap history API + paginated log.

3.4 Deployment docs

  • Device detail trap forwarding help text.
  • Health endpoint includes snmpTraps status.
  • Expanded Docker / pfSense / UniFi forwarding guide. Outstanding (see Docs)

3.5 UI

  • Trap log on Monitoring page.
  • Device detail trap forwarding help.

Exit criteria: ✅ Met on dev (v1/v2c traps).

Phase 4 — Port & interface integration ✅ (dev)

Goal: SNMP interface state visible in Ports/Racks, not only Monitoring.

4.1 Data flow

  • On successful ifOperStatus poll or trap: update ports.linkState when deviceMonitors.portId set.
  • Match by snmpIfIndex when portId is unset.
  • Dashboard / Ports views show “SNMP verified” badge.
  • Visualizer: optional edge styling from SNMP-verified links.

4.2 Smarter port matching

  • Import flow: match ifName / ifDescr to Rackpad port name (fuzzy + manual confirm UI).
  • Store ports.snmpIfIndex for stable re-sync.
  • Discover preview shows matched Rackpad port name.

4.3 Walk enhancements

  • Optional ifHighSpeed → port speed field on import (when empty).
  • Bridge MIB / MAU for SFP status (devices that support it).

Exit criteria: ✅ Met on dev.

Phase 5 — Vendor profiles & inventory sync 🟡 (v1 on dev; exit criteria not met)

Goal: Optional auto-maintain VLANs/IPAM (firewall/switch/router); highest value, highest risk.

Exit criteria gap: Plan called for a vendor-specific profile (e.g. pfSense). Only generic Q-BRIDGE + IP-MIB profiles shipped in v1. See Outstanding work → P0.

5.1 Profile framework

  • server/lib/snmp-profiles/ — one file per vendor family.
  • Profile schema with collectors for VLANs/subnets.
  • Built-in profiles:
    1. Generic IF-MIB (Phase 1–4 interface monitors)
    2. Q-BRIDGE-MIB (q-bridge-vlans)
    3. IP-MIB subnets (ip-adent-subnets)
    4. Combined (standard-l2-l3)
    5. pfSense / OPNsense — deferred
    6. UniFi / MikroTik / FortiGate — deferred

5.2 Sync engine

  • POST /api/snmp-sync/preview — dry-run diff for VLANs/subnets.
  • POST /api/snmp-sync/apply — admin-only, lab-scoped, with conflict policy:
    • merge — add missing only
    • mirror — create/update/delete with allowDeletes confirmation
  • Never delete subnets with IP assignments (blocked in preview/apply).
  • DHCP scope apply (preview-only message in v1).

5.3 UI

  • Device → Monitoring tab → SNMP inventory sync panel.
  • Scheduled sync (cron): optional interval per device (e.g. daily).

5.4 Safety

  • All sync writes audited.
  • Rollback = restore from admin backup (existing feature).
  • Feature flag: SNMP_INVENTORY_SYNC=1.

Exit criteria: ❌ Not met — pfSense (or equivalent) profile + confirmed manual lab run still required.

Phase 6 — Enterprise & scale (not started)

  • SNMP Inform ack support (reliable traps).
  • Bulk polling queue with concurrency limit (avoid N× simultaneous walks).
  • Per-lab SNMP rate limits.
  • Metrics export (Prometheus): poll latency, trap rate, failures.
  • i18n for all new SNMP UI strings (342+ key pattern).

Suggested release mapping

Release Phases Theme Status
1.6.0 Phase 1 Interface monitors + port linkage + presets ✅ On dev, unreleased
1.7.0 Phase 2 SNMPv3 ✅ On dev, unreleased
1.8.0 Phase 3 Trap receiver + alerts ✅ On dev, unreleased
1.9.0 Phase 4 Ports/visualizer integration ✅ On dev, unreleased
2.0.0 Phase 5 pfSense or full sync + docs 🟡 v1 on dev; vendor profile + docs outstanding

Adjust based on user demand; traps and v3 can be swapped if community prioritizes v3 first.

Dependencies & risks

Risk Mitigation
Docker non-root cannot bind 162 Default 1162 + doc port mapping
SNMP from container can’t reach mgmt VLAN Doc host networking / macvlan; same as ICMP today
Vendor MIBs undocumented Start IF-MIB + Q-BRIDGE; profiles contributed via JSON
Sync destroys manual IPAM Preview-only default; merge mode; no auto-delete v1
SNMPv3 crypto complexity Phase 2 scoped to authNoPriv + AES128 authPriv
Secret storage Instance encryption key; document backup implications

Testing strategy

  1. Unit: BER encode/decode, walk termination, OID parsing, match modes.
  2. Integration: In-process UDP SNMP responder (existing pattern in app.test.ts).
  3. Fixtures: Recorded PCAP or hex payloads for trap parsing regression tests.
  4. Manual lab matrix: Linux (snmpd), pfSense, one managed switch, one UniFi/AP if applicable.
  5. CI: No live network; all automated tests use mock responders.

Documentation deliverables

  • README env vars: RACKPAD_SECRET_KEY, SNMP_TRAP_*, SNMP_INVENTORY_SYNC (partial).
  • README section: full SNMP monitoring setup (community, firewall, Docker ports). Outstanding
  • Admin guide: trap forwarding, v3 credentials, sync preview. Outstanding
  • OID cookbook: common IF-MIB examples for homelab gear. Outstanding
  • Update docs/BETA_1_5_ISSUE_MAP.md #35 when phases ship. Outstanding
  • CHANGELOG entries per release. Outstanding

Open decisions

All previously open items are resolved — see Resolved decisions (2026-06) above. New decisions for next sprint:

  1. pfSense vs UniFi as first vendor-specific profile (recommend pfSense).
  2. Release cadence: single 2.0.0 bundle vs incremental 1.6–1.9 tags on dev.
  3. Scheduled sync: device-level vs lab-level cron.

Related issues

  • #35 — SNMP monitoring and traps (primary)
  • #28 — Services per device (SNMP could populate service list later)
  • #34 — WiFi port type (orthogonal; possible future wireless MIB)
  • Monitoring bulk actions — extend to “Add SNMP interface monitors” for selected devices