doc updates
This commit is contained in:
1 parent
7e1bd4a9a4
commit
a511ff532e
26 files changed
+573
-770
No files matched your search
@@ -0,0 +1,63 @@
|
||||
# P3 — Integration & hardening
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Status | Done (I6 #5 deferred to Backlog) |
|
||||
| Owner | Ari |
|
||||
| Phase | 3 (single track) |
|
||||
| Depends on | WS-E, WS-F, WS-G (and transitively A–D) |
|
||||
| Blocks | Release |
|
||||
| Owned files | `src/main.rs` (serve wiring), `systemd/skyg-linux-tracker.service`, `README.md`, `tests/` |
|
||||
|
||||
## Goal
|
||||
|
||||
Wire every surface into one axum server, prove the negative paths, and ship the unit file and docs. This is the only place the surfaces meet.
|
||||
|
||||
## Tasks
|
||||
|
||||
Tick these in [`TODO.md`](../../TODO.md).
|
||||
|
||||
- **I1** `slinuxm serve` wiring in `main.rs`:
|
||||
1. Load config, then `telemetry::init`, then `db::open` when auth is enabled, then construct sources and `AppState`.
|
||||
2. Build the protected router: `.nest("/api/v1", api::router(state))` and `.nest_service("/mcp", mcp::service(state))`, then `.layer(auth::layer(state))`.
|
||||
3. Build the public router with `/healthz`.
|
||||
4. `public.merge(protected).layer(TraceLayer::new_for_http())` (review R3).
|
||||
5. Spawn the metrics and log export tasks when enabled.
|
||||
6. On SIGINT or SIGTERM: cancel `state.shutdown` so SSE streams and background tasks end, run `axum::serve(...).with_graceful_shutdown`, then drop the telemetry guard to flush OTel (review G3).
|
||||
- **I2** Integration tests in `tests/` covering Verification #6:
|
||||
- A missing or invalid token gets 401 on `/api/v1/*` and `/mcp`. `/healthz` returns 200 without a token.
|
||||
- `auth.enabled = false` with `bind = 0.0.0.0` makes startup exit non-zero with a clear message.
|
||||
- A missing Docker socket gives 503 on docker routes while systemd routes still return 200.
|
||||
- SIGTERM with an open SSE client exits within a few seconds.
|
||||
- **I3** `systemd/skyg-linux-tracker.service`:
|
||||
- `ExecStart=/usr/local/bin/slinuxm serve --config /etc/skyg-linux-tracker.toml`
|
||||
- A dedicated `User=` (for example `skyg`), or `DynamicUser=yes` if the token CLI story still works. Decide and note it.
|
||||
- `StateDirectory=skyg-linux-tracker`, `StateDirectoryMode=0700`
|
||||
- `ProtectSystem=strict`, `ProtectHome=yes`, `PrivateTmp=yes`, `NoNewPrivileges=yes`, `ProtectKernelTunables=yes`, `ProtectControlGroups=yes`, `RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6`, `LockPersonality=yes`, `MemoryDenyWriteExecute=yes`
|
||||
- `SupplementaryGroups=systemd-journal`. Add `docker` commented out with a root-equivalence warning (DEC-6).
|
||||
- **I4** `README.md`:
|
||||
- What it is and how to build it (`devenv shell`, `cargo build --release`).
|
||||
- Install: binary, config, unit file.
|
||||
- Config reference, or a pointer to `config.example.toml` and the env-var naming.
|
||||
- Token workflow: `sudo -u skyg slinuxm token create <name>`.
|
||||
- REST endpoint list, and MCP client setup with a bearer header example.
|
||||
- OTel setup and the hardened Docker socket-proxy option.
|
||||
- **I5** Release build checks:
|
||||
- `cargo build --release`.
|
||||
- `ldd target/release/slinuxm` lists only libc, libsystemd and libsystemd's own deps.
|
||||
- Record the binary size in the log.
|
||||
- **I6** Run Verification #1–#6 from the [verification checklist](../../ARCHITECTURE.md#verification) by hand on a real systemd + Docker host and record the results in the log.
|
||||
|
||||
## Done when
|
||||
|
||||
- I2 tests pass in `cargo test`.
|
||||
- I6 results are logged. #1–#4 and #6 pass; #5 (OTel) is deferred to the Backlog (**I6-5**) because the external collector on minipc1 is down.
|
||||
- The unit file starts the service on a clean host with only the binary, config and unit installed (met on minipc1, 2026-10-19).
|
||||
|
||||
## Log
|
||||
|
||||
- 2026-10-15: Card created.
|
||||
- 2026-10-15: Implemented on `p3/integration`. I1-I5 done; I6 partial. Router assembly lives in `src/server.rs` (`build_router`, `serve_listener`) so tests and `main` share it. Shutdown: signal -> cancel token -> graceful serve ends -> await exporter handles -> `guard.shutdown().await` -> close pool. `token` subcommand does not init telemetry. Unit uses a static `User=skyg` (not DynamicUser) so `sudo -u skyg slinuxm token ...` hits the same DB. I2: 8 tests in `tests/integration.rs` (raw HTTP client, no new deps). Release binary 19 MB; `ldd`: libsystemd, libgcc_s, libm, libc only.
|
||||
- I6 live results (release binary, loopback, real token via CLI, real systemd/journal/docker on this host): #1 build/tests pass; #2 serve + token create pass; #3 REST incl. `curl -N` journal SSE pass (docker log follow SSE not exercised live); #4 MCP initialize, tools/list, prompts/list, resources/list, 5 tool calls, no-token 401, bad Origin 403 pass via curl (MCP Inspector not run; not all 8 tools called); #5 OTel NOT RUN (otelcol-contrib not on PATH, devenv shell not started via `devenv up`); #6 pass via tests (401, auth-off+0.0.0.0 refuses, SIGTERM with open SSE exits 0 in <1s); missing-docker-socket 503 covered by WS-E fake test, not live. Unit file not installed on a clean host (only `systemd-analyze verify`, which cannot fully run here).
|
||||
- 2026-10-15: Review follow-ups applied. Shutdown drain and exporter awaits are bounded (10s each) and the unit uses TimeoutStopSec=30; new test: SIGTERM with an open MCP session and an in-flight 60s `tail_journal` exits 0. Unit: SystemCallFilter, ProtectProc=invisible, ProcSubset=pid, RestrictSUIDSGID, UMask=0077; docker.service is `After=` only. Hardening was run via `systemd-run --user` with the same sandbox properties (REST systemd/journal/docker and SIGTERM all worked); not run as a system unit with User=skyg/StateDirectory. Host allowlist guard on `/api/v1` when auth is disabled (test). `server.port = 0` rejected (test). Integration tests extended (13 tests): unmatched paths (401 with auth on, route existence not disclosed), POST 401/405, GET/DELETE /mcp without token, revoked token, Basic scheme, good Origin, missing docker socket (503 vs 200). SIGTERM tests use env_clear; the pick-port-then-drop race remains (port 0 is now rejected by config).
|
||||
- 2026-10-19: I6 re-run on minipc1 (real NixOS host) through the installed `skyg-linux-tracker.service` (in `/etc/systemd/system`, enabled, active since 15:58, 0 restarts). All 8 MCP tools were called live and passed: `list_systemd_units`, `list_containers`, `list_systemd_timers`, `get_journal_logs` (priority + lines), `get_systemd_unit` (including the `not_found` error), `get_container`, `get_container_logs`, `tail_journal`. Verification #1–#4 and #6 pass; the I3 clean-host install is satisfied. **#5 OTel is deferred to the Backlog (I6-5)**: `opentelemetry-collector.service` on minipc1 is failed (`var-lib-loki.mount` also failed), so `slinuxm` logs `TonicLogsClient export failed ... Connection refused`. `slinuxm` itself exports fine; the fault is external (X-1). Not covered live: docker log-follow SSE (B-1), REST/auth/TLS (B-2). Whether minipc1 is deployed from this repo's `nixosModules.default` is unknown. Card moved to Done.
|
||||
Reference in new issue
Block a user