Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YShymaPrXmc3KYRUg2HMSs
6.5 KiB
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
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
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:
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 |
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):
{
"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:
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 with CONTAINERS=1 EVENTS=1 POST=0, exposed as a unix socket (or loopback TCP through a socat bridge), then:
[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
[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
ldd /usr/local/bin/slinuxm # libc, libm, libgcc_s, libsystemd and its dependencies only
Development
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/.