Container details now carry the image id and the HostConfig resource limits
(CPU cores and shares, memory and swap bytes, pids, device requests) plus sandbox flags
(privileged, read-only rootfs, network mode, restart policy), with null meaning unlimited. A new
GET /api/v1/docker/containers/{name}/stats returns one live sample: CPU percent
of one core, memory working set, processes, block IO and network bytes. Peers
proxy the new route.
Env, labels, command lines and mounts are deliberately excluded from the payload.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
121 lines
11 KiB
Markdown
121 lines
11 KiB
Markdown
# REST and MCP reference
|
|
|
|
Full endpoint and MCP client reference. Everyday usage is in [operations.md](operations.md); the design is in [ARCHITECTURE.md](../ARCHITECTURE.md#rest-api).
|
|
|
|
## Generated reference (OpenAPI)
|
|
|
|
[`openapi.json`](openapi.json) is a committed OpenAPI 3.1 description of everything this binary serves: every REST route with its parameters and response schemas, the error shape, the MCP endpoint (`POST`, the standalone `GET` stream and the session `DELETE`), and an `x-mcp-tools` extension listing each MCP tool with the description and input JSON Schema the tool router reports (eight tools, or ten with `[peers] enabled = true`). `tests/openapi.rs` keeps it true: it fails if a route of the real router is undocumented, if a tool is missing from `x-mcp-tools`, or if the file is stale.
|
|
|
|
- `GET /api/v1/openapi.json` returns the document for the running instance, behind the same bearer token as the rest of `/api/v1`. Peer routes appear only when peers are enabled.
|
|
- `GET /docs` renders it with Redoc. The page (`/docs`) and the Redoc 2.5.4 bundle (`/docs/redoc.standalone.js`, embedded in the binary) are public, static and hold no host data; the page asks for a bearer token, keeps it in `sessionStorage` and sends it only to `GET /api/v1/openapi.json`, so the spec itself stays behind auth. With `[auth] enabled = false` it loads without asking. The page answers with a strict `Content-Security-Policy` (no external origins), so nothing is fetched from a CDN. Redoc shows REST operations; the MCP tools in `x-mcp-tools` are in the JSON, not in the rendered page.
|
|
- `slinuxm openapi [--peers]` prints the same document offline: no config file, no token, no server, no port. `--peers` describes a consolidator; without it you get the peer-less instance.
|
|
- Regenerate after changing a route, a tool, a response type or the crate version:
|
|
|
|
```sh
|
|
cargo run -- openapi --peers > docs/openapi.json
|
|
```
|
|
|
|
## REST
|
|
|
|
Base: `http://127.0.0.1:1984`. Errors are `{"error":{"code","message"}}`.
|
|
|
|
| Route | Notes |
|
|
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
| `GET /healthz` | public, `{"status":"ok","version":...}`, `version` is the build stamp `YYYY.MM.DD-<branch>-<sha>` |
|
|
| `GET /docs`, `GET /docs/redoc.standalone.js` | public static Redoc viewer for the OpenAPI document, see [Generated reference](#generated-reference-openapi) |
|
|
| `GET /api/v1/systemd/units?state=failed` | `state` is an active state (`failed`, `active`, ...) |
|
|
| `GET /api/v1/systemd/units/{name}` | one unit with details; read-only, so only units systemd has loaded (unloaded or unknown is 404) |
|
|
| `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}` | limits and sandbox flags (`resources`), `image_id`; never env, labels or commands |
|
|
| `GET /api/v1/docker/containers/{name}/stats` | one live sample: CPU percent, memory, pids, block IO, network |
|
|
| `GET /api/v1/docker/containers/{name}/logs?tail=&since=&follow=0\|1` | JSON, or SSE with events `stdout`/`stderr` |
|
|
| `GET /api/v1/peers` | consolidator only; sorted status list; absent when peers are disabled |
|
|
| `GET /api/v1/peers/{peer}` | one peer's status object; unknown name is 404 |
|
|
| `GET /api/v1/peers/{peer}/...` | GET-only pass-through of that peer's documented routes |
|
|
| `GET /api/v1/openapi.json` | this document, OpenAPI 3.1 (see [Generated reference](#generated-reference-openapi)) |
|
|
|
|
```sh
|
|
TOKEN=slinuxm_...
|
|
curl -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:1984/api/v1/systemd/units?state=failed'
|
|
curl -N -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:1984/api/v1/journal/follow?priority=err'
|
|
```
|
|
|
|
### Peers
|
|
|
|
Present only when `[peers] enabled = true`. The same inbound token as the rest of `/api/v1` is required. `GET /api/v1/peers` returns `{"peers":[...]}` sorted by name, including disabled peers. `GET /api/v1/peers/{peer}` returns one object, not wrapped:
|
|
|
|
```json
|
|
{
|
|
"name": "beta",
|
|
"enabled": true,
|
|
"url": "http://beta:1984",
|
|
"server": {
|
|
"up": true,
|
|
"since": "2026-10-19T10:00:00Z",
|
|
"last_checked": "2026-10-19T10:00:09Z",
|
|
"last_error": null,
|
|
"latency_ms": 1
|
|
},
|
|
"api": {
|
|
"up": true,
|
|
"since": "2026-10-19T10:00:00Z",
|
|
"last_checked": "2026-10-19T10:00:05Z",
|
|
"last_error": null,
|
|
"latency_ms": 7,
|
|
"auth": "ok",
|
|
"peer_version": "0.1.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
`server` is the TCP check and `api` is the authenticated ping. `auth` is `ok`, `rejected` or `unknown`. Before the first check, `up` is false, `auth` is `unknown` and the timestamps are null. An unknown name is `404` `{"error":{"code":"not_found","message":"peer <name>: unknown peer"}}`.
|
|
|
|
`GET /api/v1/peers/{peer}/{path}` forwards a GET to that peer and returns the peer's status and body. The path has to be one of the documented read routes: `systemd/units`, `systemd/units/{name}`, `systemd/timers`, `journal`, `journal/follow`, `docker/ps`, `docker/containers/{name}`, `docker/containers/{name}/stats`, `docker/containers/{name}/logs`. `ping` and `peers/...` are not forwarded. `systemd/units/{name}` accepts exactly what the local route accepts, including escaped names (`mnt-data\x2dbackup.mount`, sent as `%5C`) and `-.mount`. `..`, encoded slashes, NUL/CRLF, a second encoding layer and any other path are `400` `peer <name>: path not allowed`. Query keys are the same ones the local route accepts (`state`, `unit`, `priority`, `lines`, `since`, `all`, `tail`, `follow`); anything else is `400` `peer <name>: unsupported query parameter`. The `unit` value is checked with the same unit-name rule as `systemd/units/{name}`, so escaped names work as both `%5C` and a literal backslash (`/api/v1/peers/beta/journal?unit=mnt-data%5Cx2dbackup.mount`). The caller's `Authorization` and `Cookie` are not forwarded; the consolidator sends the peer's own token.
|
|
|
|
A request that already has `x-slinuxm-hop` is `400` `peer <name>: chained requests are not allowed`. Other methods are `405`. `journal/follow` and docker logs with `follow=1` are `text/event-stream` with `Cache-Control: no-cache`, like the local follow routes, cut off at `limits.max_follow_secs` or shutdown. Bodies larger than `peers.max_response_bytes` are `503` `peer <name>: oversize`. Only `2xx` from the peer is passed through; any other status becomes the section 4 error for that peer (a peer `404` is `404 not_found`, a peer `401`/`403` is `503 peer rejected credentials`, anything else is `503 http_<code>`), so a redirect or the peer's own error body never reaches the caller.
|
|
|
|
Every proxied response for a configured peer, including the consolidator's own errors (`400`, `404`, `500`, `503`), carries `x-slinuxm-peer: <name>`. A request for an unknown or malformed peer name is `404` with no peer header: it did not come from a peer.
|
|
|
|
A peer failure never becomes `401`: a peer refusing the consolidator's token is `503` `peer <name>: peer rejected credentials`, so the caller does not re-authenticate against the wrong host.
|
|
|
|
```sh
|
|
curl -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:1984/api/v1/peers/beta/systemd/units?state=failed'
|
|
```
|
|
|
|
## MCP
|
|
|
|
Endpoint: `http://127.0.0.1:1984/mcp` (Streamable HTTP). `POST /mcp` carries the JSON-RPC messages; the default session mode also serves `GET /mcp` (standalone `text/event-stream` for server-to-client messages) and `DELETE /mcp` (end the session named by `Mcp-Session-Id`; 202 on success). 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`) two resources (`systemd://units/failed`, `docker://containers`) and two resource templates (`systemd://unit/{name}`, `docker://container/{name}`, same JSON as `get_systemd_unit` and `get_container`; percent-encode unusual characters in the name). 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:1984/mcp",
|
|
"headers": { "Authorization": "Bearer slinuxm_..." }
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Claude Code: `claude mcp add --transport http linux-tracker http://127.0.0.1:1984/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:1984/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:1984"]`) and any browser origins to `server.allowed_origins`. With `auth.enabled = false` (loopback only), REST requests are checked against a Host allowlist (loopback names, `server.bind` and `server.allowed_hosts`) and get `403` otherwise, to blunt DNS rebinding. There is no Origin check on REST and no token in that mode, so keep auth enabled on any multi-user host. If the host is reachable beyond a trusted network, enable native TLS (see [tls.md](tls.md)) or terminate TLS in a reverse proxy.
|