[Gerrrt]

Closes #97.

#97 asks for two things about the MokerLink management UI: a name instead of 10.7.7.2, and a certificate that verifies. They read as one task — give it a name so the lab CA has something to issue for — and they are not. ADR-0017 grants one half and closes the other as unavailable.

The check that decided it

From prometheus (10.0.99.20), against the live switch, 2026-09-04:

Check	Result
TCP 80	open
TCP 443	no listener
GET /	200, a two-frame frameset over cookie.cgi and login.cgi
<title>	G2402GSM
Server: / Date:	neither sent

A Realtek-SDK web UI. No TLS listener to point a certificate at, and no import to put one in. targets/blackbox.yaml already claimed "http only — 443 is dropped"; this is that re-checked rather than inherited.

So the certificate half is blocked on the device, not on the name. The issue's framing — that a switch reached by IP "cannot be given a certificate that verifies, so it stays on plain HTTP" — has the dependency backwards here. It stays on plain HTTP because that is all it serves, and it would stay there with a name.

That is neo's third firmware limit after the undeletable SNMP community row (#84) and the missing SNMPv3 (#85). Three is the argument for replacing the switch rather than for another workaround, so ADR-0017 puts TLS management into the selection criteria for whatever replaces it.

Two things the issue left open

• Not blocked behind ADR-0008. ADR-0010 already settled that clients keep pfSense as their only resolver and "the matrix.elysium host overrides stay where they are." Overrides were never downstream of AdGuard.
• 10.7.7.2 is not undocumented. The runbook called it "outside every documented subnet, which is the harder half." network.md has a LAN section for it. What is true is narrower — it is outside the 10.0.x convention every other management address follows, which is the typo risk the issue names and not a routing problem. Both halves of that sentence are corrected in place rather than left.

Rejected

A TLS reverse proxy terminating https://neo.matrix.elysium was considered. It puts the device you open when the network is wrong behind Unbound on morpheus and a container on another host — reached through the switch being diagnosed. The credential would still cross the last hop in clear.

Renumbering onto 10.0.99.x is rejected too, not deferred: it means re-addressing the firewall's LAN interface, the SNMP and blackbox targets that hard-code the address, and two ADR-0013 rules, to make one address prettier on the box that locks everything out if it goes wrong.

Changes

• ADR-0017 — the decision, the check, and the rejected alternatives.
• add-a-host-override.md — neo added to the table; the stale "these four were applied" note and the four-name verify block corrected; the closing paragraph rewritten.
• network.md — the name, and that the UI is plain HTTP and cannot be otherwise.
• security.md — the cleartext admin credential as an accepted residual. Worth being precise about: it crosses the wire through neo itself, the device the password protects, and unlike the SNMP communities beside it, this one is read-write.
• blackbox.yaml — a via: dns twin for switch-ui, and a note that http_2xx_plain is permanent here rather than a placeholder awaiting a certificate.
• blackbox.test.yaml — switch-ui was the worked example for "an endpoint with no dns twin" and now has one. The synthetic series would still pass, which is precisely why it is a bad example; swapped for ups-ui.

Before merging

The host override must be applied by hand first — pfSense UI, config backup first, per the runbook. neo.matrix.elysium is NXDOMAIN as of this writing. If the blackbox target lands first, EndpointNameNotResolving fires, truthfully, for planned work. The wiki was sequenced the same way.

Verification

./scripts/validate.sh passes in full (2 skips, both "not the deployment checkout"). promtool check rules + test rules run green across all 7 test files.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The host-override verification runbook text incorrectly implies five distinct IP addresses despite intentional duplicates, which can mislead operators during validation.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR documents and operationalizes the decision to give the MokerLink switch management UI a stable DNS name (neo.matrix.elysium) while explicitly accepting that the UI remains plain HTTP due to firmware limitations (no TLS listener / no cert import), and updates monitoring + runbooks accordingly.

Changes:

• Adds ADR-0017 capturing the HTTP-only constraint and rejecting TLS reverse-proxy/renumbering alternatives.
• Updates docs/runbooks/network/security/roadmap to reflect the new neo hostname and the accepted cleartext-admin residual risk.
• Updates Prometheus blackbox targets to probe the switch UI via both address and DNS, and adjusts rule tests to use a better “no dns twin” example.

File summaries

File	Description
docs/adr/0017-name-the-switch-and-leave-its-ui-on-plain-http.md	New ADR documenting the decision, device constraints, and rejected alternatives.
docs/network.md	Documents neo.matrix.elysium → 10.7.7.2 and states UI remains HTTP-only.
docs/roadmap.md	Updates #97 roadmap entry to match ADR-0017’s split decision and sequencing.
docs/runbooks/add-a-host-override.md	Adds neo to pfSense host overrides procedure and expands verification guidance.
docs/security.md	Records the HTTP-only UI as an accepted residual risk and ties it to ADR-0017.
stacks/observability/prometheus/targets/blackbox.yaml	Adds a via: dns blackbox target for switch-ui and clarifies module permanence.
stacks/observability/prometheus/tests/blackbox.test.yaml	Replaces the “no dns twin” worked example from switch-ui to ups-ui.

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.