Subprocess-backed endpoints

Several endpoints shell out to platform tooling and are correspondingly slow.
Client timeouts should account for this: /drivers may take one to two seconds
on a dense chassis and issues up to seven distinct tool invocations;
/hardware and /hardware/test invoke ipmitool with timeouts up to ten
seconds; /about invokes vppctl and uname; /audit/journal invokes
journalctl with a fifteen-second ceiling and returns 504 if it is exceeded.

The Controller Passthrough

The single most important endpoint for an integrator building a complete NMS
feed is not in the /api/bng namespace at all.

GET|POST|PUT|PATCH|DELETE /v1/<path>

This is a transparent reverse proxy onto the BNG controller's own REST surface —
the interface described in the companion BNG Telemetry API Theory of
Operations. It is mounted at the application root rather than under /api/bng,
because it must mirror the controller's native /v1 namespace exactly.

What this means in practice. A single API key against
https://<box>:8443 reaches both planes:

https://<box>:8443/api/bng/health              → operational health (composed)
https://<box>:8443/v1/bng/counters             → raw QoS band counters
https://<box>:8443/v1/bng/sessions             → raw session inventory
https://<box>:8443/v1/bng/sessions/{ip}        → full subscriber record
https://<box>:8443/v1/bng/pools                → address pool occupancy
https://<box>:8443/v1/bng/plans                → service rate tiers

The integrator does not need a second credential, a second port, a second TLS
trust relationship, or network reachability to the controller's loopback
listener. The passthrough is the bridge between the two documents.

Forwarding semantics. The query string and the raw request body are forwarded
unchanged. Hop-by-hop headers are stripped in both directions, so an upstream
Connection: close cannot prematurely terminate the downstream connection.
Redirects are not followed — a 3xx from the controller is returned to the
caller as a 3xx. The response is fully buffered rather than streamed. The
timeout is twenty seconds.

Credential handling. If the caller presents an Authorization header, it is
preserved verbatim and passed to the controller, which applies its own role
check. If the caller is a browser session with no Authorization header,
QuantumTouch injects the session's per-session controller bearer, which causes
the controller to attribute the request to that operator rather than to an
anonymous caller. For a script the first path applies: your key travels
through and the controller sees it.

Failure. If the controller is unreachable the proxy returns 502 with
{"ok": false, "error": "controller unreachable: …"}.

A defence-in-depth note worth understanding: authorisation is applied twice on
this path. QuantumTouch gates the proxy route, and the controller independently
evaluates the bearer against its own role model. A permission that one layer
would grant and the other would not is denied.

System State and Health