P3: wire serve end to end, integration tests, unit file, README
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YShymaPrXmc3KYRUg2HMSs
This commit is contained in:
1 parent
936efaf97e
commit
acedb9522e
10 files changed
+637
-16
No files matched your search
@@ -0,0 +1,145 @@
|
||||
# skyg-linux-tracker
|
||||
|
||||
A small, read-only monitor for a single Linux host. One binary, `slinuxm`, serves:
|
||||
|
||||
- a REST API (with Server-Sent Events for follow endpoints),
|
||||
- an MCP server (Streamable HTTP) so agents can inspect the host,
|
||||
- optional OpenTelemetry export (metrics and logs over OTLP).
|
||||
|
||||
Data sources are systemd (D-Bus), the journal (libsystemd) and the Docker Engine API (unix socket). Nothing here can start, stop or modify anything.
|
||||
|
||||
## Build
|
||||
|
||||
```sh
|
||||
devenv shell # toolchain, pkg-config, libsystemd, otelcol-contrib
|
||||
cargo build --release # target/release/slinuxm
|
||||
```
|
||||
|
||||
Without devenv you need a Rust toolchain, `pkg-config` and the libsystemd development files.
|
||||
|
||||
## Install
|
||||
|
||||
```sh
|
||||
sudo install -m 0755 target/release/slinuxm /usr/local/bin/slinuxm
|
||||
sudo useradd --system --no-create-home --shell /usr/sbin/nologin skyg
|
||||
sudo install -m 0644 config.example.toml /etc/skyg-linux-tracker.toml # then edit
|
||||
sudo install -m 0644 systemd/skyg-linux-tracker.service /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now skyg-linux-tracker
|
||||
```
|
||||
|
||||
The unit runs as the `skyg` user with `SupplementaryGroups=systemd-journal` and a private `StateDirectory` (`/var/lib/skyg-linux-tracker`, mode 0700) holding the token database. Its sandbox options are listed in the unit file.
|
||||
|
||||
### Config
|
||||
|
||||
See `config.example.toml`; every value shown is the default. Precedence, lowest to highest: defaults, config file, `SKYG_*` environment variables (nesting with `__`, for example `SKYG_SERVER__PORT`), CLI flags. `slinuxm --print-config` prints the effective configuration with secrets redacted.
|
||||
|
||||
Startup refuses `auth.enabled = false` on a non-loopback `server.bind`.
|
||||
|
||||
## Tokens
|
||||
|
||||
All `/api/v1/*` and `/mcp` requests need `Authorization: Bearer <token>`. `/healthz` is public. Tokens are stored hashed (sha256) in SQLite, and the plaintext is shown once.
|
||||
|
||||
Run the token CLI **as the service user** so the database keeps the right owner and mode:
|
||||
|
||||
```sh
|
||||
sudo -u skyg slinuxm token create my-laptop --config /etc/skyg-linux-tracker.toml
|
||||
sudo -u skyg slinuxm token list --config /etc/skyg-linux-tracker.toml
|
||||
sudo -u skyg slinuxm token revoke my-laptop --config /etc/skyg-linux-tracker.toml
|
||||
```
|
||||
|
||||
Revocation takes effect immediately; no restart is needed.
|
||||
|
||||
## REST
|
||||
|
||||
Base: `http://127.0.0.1:9109`. Errors are `{"error":{"code","message"}}`.
|
||||
|
||||
| Route | Notes |
|
||||
|---|---|
|
||||
| `GET /healthz` | public, `{"status":"ok","version":...}` |
|
||||
| `GET /api/v1/systemd/units?state=failed` | `state` is an active state (`failed`, `active`, ...) |
|
||||
| `GET /api/v1/systemd/units/{name}` | one unit with details |
|
||||
| `GET /api/v1/systemd/timers` | |
|
||||
| `GET /api/v1/journal?unit=&priority=err&lines=100` | priority by name or number |
|
||||
| `GET /api/v1/journal/follow?unit=&priority=` | SSE, event `journal` |
|
||||
| `GET /api/v1/docker/ps` | `503` when Docker is unavailable |
|
||||
| `GET /api/v1/docker/containers/{name}` | |
|
||||
| `GET /api/v1/docker/containers/{name}/logs?tail=&since=&follow=0\|1` | JSON, or SSE with events `stdout`/`stderr` |
|
||||
|
||||
```sh
|
||||
TOKEN=slinuxm_...
|
||||
curl -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:9109/api/v1/systemd/units?state=failed'
|
||||
curl -N -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:9109/api/v1/journal/follow?priority=err'
|
||||
```
|
||||
|
||||
## MCP
|
||||
|
||||
Endpoint: `http://127.0.0.1:9109/mcp` (Streamable HTTP). Eight tools (`list_systemd_units`, `get_systemd_unit`, `list_systemd_timers`, `get_journal_logs`, `tail_journal`, `list_containers`, `get_container`, `get_container_logs`), two prompts (`diagnose_unit`, `container_health_report`) and two resources (`systemd://units/failed`, `docker://containers`). Log content is untrusted data and is labelled as such in tool results.
|
||||
|
||||
Generic client config (header-capable clients):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"linux-tracker": {
|
||||
"url": "http://127.0.0.1:9109/mcp",
|
||||
"headers": { "Authorization": "Bearer slinuxm_..." }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Claude Code: `claude mcp add --transport http linux-tracker http://127.0.0.1:9109/mcp --header "Authorization: Bearer $TOKEN"`.
|
||||
|
||||
Inspector: `npx @modelcontextprotocol/inspector`, transport Streamable HTTP, add the bearer header.
|
||||
|
||||
Raw handshake with curl:
|
||||
|
||||
```sh
|
||||
curl -si -X POST http://127.0.0.1:9109/mcp \
|
||||
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json, text/event-stream' \
|
||||
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
|
||||
```
|
||||
|
||||
### Origin and Host checks
|
||||
|
||||
`/mcp` validates `Origin` and `Host` to defend against DNS rebinding from browsers. Loopback names, `server.bind` and the configured port are accepted by default. Requests without an `Origin` header (non-browser clients) pass this check, so the bearer token remains the real gate. If you bind to `0.0.0.0` or serve behind a name, add the names clients use to `server.allowed_hosts` (for example `["monitor.lan:9109"]`) and any browser origins to `server.allowed_origins`. Terminate TLS in a reverse proxy if the host is reachable beyond a trusted network; the server itself speaks plain HTTP.
|
||||
|
||||
## Docker access
|
||||
|
||||
Reading the Docker socket directly requires group `docker`, which is root-equivalent. The unit file has this commented out. Prefer a read-only socket proxy that allows only `GET /containers/*`, `/events` and `/version`, for example [tecnativa/docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy) with `CONTAINERS=1 EVENTS=1 POST=0`, exposed as a unix socket (or loopback TCP through a socat bridge), then:
|
||||
|
||||
```toml
|
||||
[sources]
|
||||
docker_socket = "/run/docker-proxy/docker.sock"
|
||||
```
|
||||
|
||||
If the socket is missing or unreadable, Docker routes return `503` and everything else keeps working.
|
||||
|
||||
## OpenTelemetry
|
||||
|
||||
```toml
|
||||
[otel]
|
||||
enabled = true
|
||||
endpoint = "http://localhost:4317" # gRPC; or http://localhost:4318 with protocol = "http/protobuf"
|
||||
export_logs = true
|
||||
```
|
||||
|
||||
Metrics are polled every `metrics_interval_secs` (systemd unit active/failed/restarts and timer next elapse; container running/healthy/uptime/restarts). Logs fan out from the journal and from Docker containers. For a local collector with a debug exporter: `devenv up` (runs `otelcol-contrib --config dev/otelcol.yaml`). On SIGTERM pending records are flushed before exit.
|
||||
|
||||
## Verifying a release binary
|
||||
|
||||
```sh
|
||||
ldd /usr/local/bin/slinuxm # libc, libm, libgcc_s, libsystemd and its dependencies only
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
```sh
|
||||
cargo test
|
||||
cargo clippy --all-targets -- -D warnings
|
||||
cargo fmt --check
|
||||
```
|
||||
|
||||
The integration tests in `tests/` start the real router on an ephemeral port with fake sources. Design notes live in `plan.md` and `plan/`.
|
||||
Reference in new issue
Block a user