Add cutsheets: planned cabling across devices and patch panels #12

New Issue

2026-11-05T10:26:24-05:00

jared commented

2026-11-05 10:26:24 -05:00

Record where every cable is meant to go, including patch panels and other passive hardware, and compare that plan with what Gandalf actually sees on the network.

Why

Gandalf only knows what it can discover through LLDP, MAC tables and the UniFi client table. That leaves real gaps:

Patch panels and wall jacks are passive, so they can't be discovered at all.
There's no record of intent, so nothing shows a cable is in the wrong port. For example, the names of ports 11 and 22 on 24RJ45-POE don't match the neighbors seen there, and it isn't clear which one is right.
Bond members share a MAC, so discovery can name only one port per bond. A cutsheet can record the rest.
The topology diagram is maintained by hand and has already drifted from reality.

Scope

Inventory

Add passive hardware that can't be discovered: patch panels with a port count and location, plus wall jacks and similar endpoints.
Refer to discovered devices and their ports rather than copying them, so renames don't break the records.

Cables

Each cable has two endpoints, each a device port, patch panel port or other endpoint.
Fields: label or ID, type (Cat6, OM3, DAC, etc.), length, color, status (planned, installed, retired) and notes.
A full run can span several cables, such as switch port → panel A port 5 → panel B port 5 → server NIC. The full path should be traceable from either end.

Plan vs. actual

Compare each planned connection with the discovered neighbor and report: matches, wrong neighbor, planned but no link, and link present but not documented.
Show "can't verify" when discovery has no answer, as with bond members, rather than reporting a false mismatch.
Show mismatches on the cutsheet page first. Whether they should also raise alerts or tickets is a separate decision, since nobody should get paged during a planned recabling.

UI

A cutsheet page that can be searched and filtered by device, panel, label and status.
A per-panel view showing each port and what it connects on both sides.
On device pages, show the planned connection in the port panel next to the discovered neighbor, with the path traced through any patch panels.
Include cutsheet items in the home page search.

Import and export

CSV import and export, plus a print-friendly view for use at the rack.

Technical notes

Add tables to schema.sql, with creation at startup like db.ensure_modem_schema. Cutsheets are long-lived records and should not be stored in monitor_state JSON.
Rows reference a device by name and port index, so decide how to handle a replaced or renamed device.
This adds write access to data people rely on, so edits should require an allowed group and record who changed what and when. Issue #3 (trusting Remote-* headers from any source) matters more once this exists and should be fixed first or alongside it.
The per-model front panel redesigns can later show planned vs. actual directly on each port.
This data can also feed the topology redesign.

Open questions

Which patch panels and other passive hardware exist today, and what are their port counts and locations?
Should rack elevation (rack unit positions) be included, or tracked separately?
Is there an existing cable labeling scheme to follow?
Should a mismatch ever raise a ticket, or stay on this page only?

Acceptance criteria

Patch panels and passive endpoints can be added, edited and removed
Cables can be recorded with status, and a multi-hop path can be traced from either end
Planned connections are compared with discovered neighbors, and "can't verify" is distinct from a mismatch
Device port panels show the planned connection beside the discovered neighbor
Cutsheet items are searchable, and the data can be exported to CSV and imported from it
A print-friendly view exists
Edits require an allowed group and are logged with user and time
Tests cover path tracing and each comparison outcome

Record where every cable is meant to go, including patch panels and other passive hardware, and compare that plan with what Gandalf actually sees on the network. ## Why Gandalf only knows what it can discover through LLDP, MAC tables and the UniFi client table. That leaves real gaps: - Patch panels and wall jacks are passive, so they can't be discovered at all. - There's no record of intent, so nothing shows a cable is in the wrong port. For example, the names of ports 11 and 22 on `24RJ45-POE` don't match the neighbors seen there, and it isn't clear which one is right. - Bond members share a MAC, so discovery can name only one port per bond. A cutsheet can record the rest. - The topology diagram is maintained by hand and has already drifted from reality. ## Scope **Inventory** - Add passive hardware that can't be discovered: patch panels with a port count and location, plus wall jacks and similar endpoints. - Refer to discovered devices and their ports rather than copying them, so renames don't break the records. **Cables** - Each cable has two endpoints, each a device port, patch panel port or other endpoint. - Fields: label or ID, type (Cat6, OM3, DAC, etc.), length, color, status (`planned`, `installed`, `retired`) and notes. - A full run can span several cables, such as switch port → panel A port 5 → panel B port 5 → server NIC. The full path should be traceable from either end. **Plan vs. actual** - Compare each planned connection with the discovered neighbor and report: matches, wrong neighbor, planned but no link, and link present but not documented. - Show "can't verify" when discovery has no answer, as with bond members, rather than reporting a false mismatch. - Show mismatches on the cutsheet page first. Whether they should also raise alerts or tickets is a separate decision, since nobody should get paged during a planned recabling. **UI** - A cutsheet page that can be searched and filtered by device, panel, label and status. - A per-panel view showing each port and what it connects on both sides. - On device pages, show the planned connection in the port panel next to the discovered neighbor, with the path traced through any patch panels. - Include cutsheet items in the home page search. **Import and export** - CSV import and export, plus a print-friendly view for use at the rack. ## Technical notes - Add tables to `schema.sql`, with creation at startup like `db.ensure_modem_schema`. Cutsheets are long-lived records and should not be stored in `monitor_state` JSON. - Rows reference a device by name and port index, so decide how to handle a replaced or renamed device. - This adds write access to data people rely on, so edits should require an allowed group and record who changed what and when. Issue #3 (trusting `Remote-*` headers from any source) matters more once this exists and should be fixed first or alongside it. - The per-model front panel redesigns can later show planned vs. actual directly on each port. - This data can also feed the topology redesign. ## Open questions - Which patch panels and other passive hardware exist today, and what are their port counts and locations? - Should rack elevation (rack unit positions) be included, or tracked separately? - Is there an existing cable labeling scheme to follow? - Should a mismatch ever raise a ticket, or stay on this page only? ## Acceptance criteria - [ ] Patch panels and passive endpoints can be added, edited and removed - [ ] Cables can be recorded with status, and a multi-hop path can be traced from either end - [ ] Planned connections are compared with discovered neighbors, and "can't verify" is distinct from a mismatch - [ ] Device port panels show the planned connection beside the discovered neighbor - [ ] Cutsheet items are searchable, and the data can be exported to CSV and imported from it - [ ] A print-friendly view exists - [ ] Edits require an allowed group and are logged with user and time - [ ] Tests cover path tracing and each comparison outcome

jared commented

2026-11-10 15:52:08 -05:00

Decisions (2026-11-10)

Hardware

One 24-port keystone patch panel at the top of the rack. The panel's rear side doesn't always go to a wall jack, so a rear endpoint can be a wall jack, a device, or unknown.
One duplex LC fiber coupler in the panel, currently unused. All 10G server links moved to DACs.
Two multimode fiber runs come down from the ceiling, both unused and capped. One is unterminated, and the other ends at a wall-plate coupler. Both are recorded as cables with status dark.
None of the cables are labeled yet. Cabling will be reorganized around a new switch whose ports sit at the left, so cords to the panel are similar lengths.

Labels

Each cord gets a short cable ID on both ends, e.g. C07. The ID stays valid when a cord is re-patched: only the cutsheet changes.
Panel ports are labeled with their destination, e.g. a room name.
The label maker is a standalone handheld with no PC connection, so Gandalf provides a "labels to make" list rather than printing. The list includes cords and panel ports that don't have a label yet.

Behaviour

Cutsheets are fully editable: add, edit, retire and delete. Every change records the user and time, and only allowed groups can edit.
Plan vs. actual mismatches show on the cutsheet and device pages. A mismatch lasting more than a day opens a P4 ticket.
Rack elevation is included: each device, panel and shelf can record its U position and height.
Panel mapping can be traced by hand, or with a trace mode. In trace mode, a cord is unplugged at the panel, Gandalf polls the switch every few seconds, and it records which port dropped.

Delivery

Inventory, cables with multi-hop paths, editing with history, plan vs. actual, undocumented-link suggestions, rack units, CSV import/export, label list, device-page integration and search.
Trace mode and mismatch tickets.

## Decisions (2026-11-10) **Hardware** - One 24-port keystone patch panel at the top of the rack. The panel's rear side doesn't always go to a wall jack, so a rear endpoint can be a wall jack, a device, or unknown. - One duplex LC fiber coupler in the panel, currently unused. All 10G server links moved to DACs. - Two multimode fiber runs come down from the ceiling, both unused and capped. One is unterminated, and the other ends at a wall-plate coupler. Both are recorded as cables with status `dark`. - None of the cables are labeled yet. Cabling will be reorganized around a new switch whose ports sit at the left, so cords to the panel are similar lengths. **Labels** - Each cord gets a short cable ID on both ends, e.g. `C07`. The ID stays valid when a cord is re-patched: only the cutsheet changes. - Panel ports are labeled with their destination, e.g. a room name. - The label maker is a standalone handheld with no PC connection, so Gandalf provides a "labels to make" list rather than printing. The list includes cords and panel ports that don't have a label yet. **Behaviour** - Cutsheets are fully editable: add, edit, retire and delete. Every change records the user and time, and only allowed groups can edit. - Plan vs. actual mismatches show on the cutsheet and device pages. A mismatch lasting more than a day opens a P4 ticket. - Rack elevation is included: each device, panel and shelf can record its U position and height. - Panel mapping can be traced by hand, or with a trace mode. In trace mode, a cord is unplugged at the panel, Gandalf polls the switch every few seconds, and it records which port dropped. **Delivery** 1. Inventory, cables with multi-hop paths, editing with history, plan vs. actual, undocumented-link suggestions, rack units, CSV import/export, label list, device-page integration and search. 2. Trace mode and mismatch tickets.

jared referenced this issue from a commit

2026-11-10 16:05:11 -05:00

Add cutsheets: planned cabling checked against discovery

jared referenced this issue

2026-11-10 16:05:26 -05:00

Add cutsheets: planned cabling checked against discovery #18

jared referenced this issue from a commit

2026-11-10 16:55:00 -05:00

Cutsheet trace mode and mismatch alerts

jared referenced a pull request that will close this issue

2026-11-10 16:55:11 -05:00

Cutsheet trace mode and mismatch alerts #19