Cutsheet: port names in UniFi that no longer fit, document a cable from topology #44

Merged
jared merged 1 commits from port-name-report into main 2026-11-15 14:21:20 -05:00
Owner

Port names in UniFi

A new section on /cutsheet, with a summary chip. It is a checklist of switch port names that no longer fit what is plugged in. Gandalf only reports them; renaming happens in UniFi.

Group Meaning Suggested name
Named after the wrong device A different known device is plugged in What is plugged in
Named after a device that moved The named device is now linked on another port Port N
Named, but nothing is plugged in Custom name, port down; shows who was last seen there (known_uplinks) Your call
Unnamed (folded) Still Port N / SFP+ N with a known device on it See below

Suggested names:

  • the device itself
  • host NIC for a server with two cables, so its two ports read differently
  • Uplink or Downlink to X between switches

Left alone:

  • good names
  • custom names over unknown devices
  • IP-only targets
  • a PDU's management port
  • a port named after a device that is only switched off

The summary chip counts only the wrong and moved names.

Against prod data today there are no wrong or moved names, because the old "Large1 / Medium1 Management" names are gone. There are 4 named but empty ports, including "WAP" on POE port 20 while the AP is on port 11, and 18 unnamed ports with suggestions.

Document a cable from the topology page

The cable panel's "not documented" now has a document it link (for admins). It opens the cutsheet's new-cable form with both ends filled in, including the NIC, and with DAC set when the cable is one. /cutsheet?... now also takes b_device, b_port and cable_type.

Already there

The cutsheet already handled the rest of what was proposed as "#3":

  • Undocumented links, with pre-filled adding.
  • Plan-vs-actual checks: a different device connected, a planned device not linked, a missing port, and two cables on one port.

So this PR only adds the topology link.

Tests

  • Results: 486 passed; flake8 and bandit are clean; eslint is unchanged at the 21-warning baseline; no em or en dashes.
  • New TestPortNameReport covers:
    • wrong, with where the named device really is
    • moved
    • empty, with last seen and where it is now
    • unnamed suggestions, including NIC, Uplink and Downlink
    • names left alone
    • a port named after a device that is off
    • no data
  • /api/cutsheet returns port_names.
  • In the preview, I followed the topology link with Playwright. The form opened with a=8SFP-AGG/4, b=storage-01/enp7s0np0 and DAC.

Screenshots

These come from anonymised preview data, with the simulated "Large1 Management" problem.

Port names Phone
Summary chip

🤖 Generated with Claude Code

## Port names in UniFi A new section on /cutsheet, with a summary chip. It is a checklist of switch port names that no longer fit what is plugged in. Gandalf only reports them; renaming happens in UniFi. | Group | Meaning | Suggested name | |---|---|---| | Named after the wrong device | A different known device is plugged in | What is plugged in | | Named after a device that moved | The named device is now linked on another port | `Port N` | | Named, but nothing is plugged in | Custom name, port down; shows who was last seen there (`known_uplinks`) | Your call | | Unnamed (folded) | Still `Port N` / `SFP+ N` with a known device on it | See below | Suggested names: - the device itself - `host NIC` for a server with two cables, so its two ports read differently - `Uplink` or `Downlink to X` between switches Left alone: - good names - custom names over unknown devices - IP-only targets - a PDU's management port - a port named after a device that is only switched off The summary chip counts only the wrong and moved names. Against prod data today there are no wrong or moved names, because the old "Large1 / Medium1 Management" names are gone. There are 4 named but empty ports, including "WAP" on POE port 20 while the AP is on port 11, and 18 unnamed ports with suggestions. ## Document a cable from the topology page The cable panel's "not documented" now has a **document it** link (for admins). It opens the cutsheet's new-cable form with both ends filled in, including the NIC, and with DAC set when the cable is one. `/cutsheet?...` now also takes `b_device`, `b_port` and `cable_type`. ## Already there The cutsheet already handled the rest of what was proposed as "#3": - **Undocumented links**, with pre-filled adding. - Plan-vs-actual checks: a different device connected, a planned device not linked, a missing port, and two cables on one port. So this PR only adds the topology link. ## Tests - Results: 486 passed; flake8 and bandit are clean; eslint is unchanged at the 21-warning baseline; no em or en dashes. - New `TestPortNameReport` covers: - wrong, with where the named device really is - moved - empty, with last seen and where it is now - unnamed suggestions, including NIC, Uplink and Downlink - names left alone - a port named after a device that is off - no data - `/api/cutsheet` returns `port_names`. - In the preview, I followed the topology link with Playwright. The form opened with `a=8SFP-AGG/4`, `b=storage-01/enp7s0np0` and `DAC`. ## Screenshots These come from anonymised preview data, with the simulated "Large1 Management" problem. | | | |---|---| | Port names ![](https://code.lotusguild.org/LotusGuild/gandalf/raw/branch/pr-44-screenshots/01-port-names.png) | Phone ![](https://code.lotusguild.org/LotusGuild/gandalf/raw/branch/pr-44-screenshots/02-port-names-phone.png) | | Summary chip ![](https://code.lotusguild.org/LotusGuild/gandalf/raw/branch/pr-44-screenshots/03-summary.png) | | 🤖 Generated with [Claude Code](https://claude.com/claude-code)
jared added 1 commit 2026-11-15 14:19:59 -05:00
Cutsheet: port names in UniFi that no longer fit, document a cable from topology
Lint / JS (eslint) (push) Successful in 23s
Lint / Python (flake8) (push) Successful in 1m10s
Lint / Notify on failure (push) Skipped
Lint / Deploy (push) Skipped
Lint / Python (flake8) (pull_request) Successful in 53s
Lint / JS (eslint) (pull_request) Successful in 11s
Lint / Notify on failure (pull_request) Skipped
Lint / Deploy (pull_request) Skipped
Security / Python Security (bandit) (push) Successful in 1m26s
Test / Python Tests (pytest) (push) Successful in 1m49s
Security / Python Security (bandit) (pull_request) Successful in 2m17s
Test / Python Tests (pytest) (pull_request) Successful in 2m12s
4dfabce2fb
- topology.port_name_report: switch port names that no longer fit what is
  plugged in, as a checklist with suggested names: named after the wrong
  device, named after a device that moved to another port, named with nothing
  plugged in (and who was last seen there), and still "Port N" with a known
  device on it. Ports named after a device that is only off are left alone.
  Gandalf only reports; it never renames anything in UniFi.
- /api/cutsheet returns it as port_names; the cutsheet page shows it as
  "Port names in UniFi", grouped, with a summary chip.
- The topology cable panel's "not documented" gets a "document it" link that
  opens the cutsheet's new-cable form with both ends, the NIC and DAC filled
  in; /cutsheet?... now takes b_device, b_port and cable_type.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
jared force-pushed port-name-report from 7745500f8e to 4dfabce2fb 2026-11-15 14:19:59 -05:00 Compare
jared scheduled this pull request to auto merge when all checks succeed 2026-11-15 14:20:04 -05:00
jared merged commit a90ce44c80 into main 2026-11-15 14:21:20 -05:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: LotusGuild/gandalf#44