doc updates
This commit is contained in:
1 parent
7e1bd4a9a4
commit
a511ff532e
26 files changed
+573
-770
No files matched your search
@@ -80,65 +80,26 @@ Notes:
|
||||
|
||||
## REST
|
||||
|
||||
Base: `http://127.0.0.1:1984`. 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; 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}` | |
|
||||
| `GET /api/v1/docker/containers/{name}/logs?tail=&since=&follow=0\|1` | JSON, or SSE with events `stdout`/`stderr` |
|
||||
Base: `http://127.0.0.1:1984`, all routes are GET and read-only. `GET /healthz` is public; everything under `/api/v1` needs the bearer token. Routes: `systemd/units`, `systemd/units/{name}`, `systemd/timers`, `journal`, `journal/follow` (SSE), `docker/ps`, `docker/containers/{name}`, `docker/containers/{name}/logs` (JSON or SSE). Docker routes return `503` when Docker is unavailable. Errors are `{"error":{"code","message"}}`.
|
||||
|
||||
```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'
|
||||
```
|
||||
|
||||
Full route table with parameters: [docs/api.md](docs/api.md).
|
||||
|
||||
## MCP
|
||||
|
||||
Endpoint: `http://127.0.0.1:1984/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`) 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_..." }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
Endpoint: `http://127.0.0.1:1984/mcp` (Streamable HTTP, same bearer token). 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, two resources and two resource templates. Log content is untrusted data and is labelled as such.
|
||||
|
||||
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 the TLS section) or terminate TLS in a reverse proxy.
|
||||
`/mcp` validates `Origin` and `Host` against DNS rebinding. 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 browser origins to `server.allowed_origins`. Generic client config, Inspector and curl handshake, and the full Origin/Host rules: [docs/api.md](docs/api.md#mcp).
|
||||
|
||||
## TLS
|
||||
|
||||
TLS is optional and off by default. With `server.tls.enabled = false` (the default) the server speaks plain HTTP exactly as before, the certificate paths are ignored and never read, and no TLS code runs. A non-loopback `bind` without TLS logs a startup warning (it is not refused).
|
||||
|
||||
Enable it in the config file or the environment (`SKYG_SERVER__TLS__ENABLED=true`, `SKYG_SERVER__TLS__CERT_FILE`, `SKYG_SERVER__TLS__KEY_FILE`):
|
||||
TLS is optional and off by default; a non-loopback `bind` without TLS logs a startup warning. Enable it with a PEM chain and key:
|
||||
|
||||
```toml
|
||||
[server.tls]
|
||||
@@ -147,18 +108,8 @@ cert_file = "/etc/skyg/tls/cert.pem" # PEM chain, leaf first
|
||||
key_file = "/etc/skyg/tls/key.pem" # PEM, PKCS#8, PKCS#1 or SEC1
|
||||
```
|
||||
|
||||
Both files are required and checked at startup; a missing, unparsable or mismatched pair stops the server with an error naming the file (key contents are never logged). REST and `/mcp` are then served over HTTPS only (plain HTTP on that port fails), and the default MCP `Origin` allowlist uses `https://` instead of `http://`. Add your public names to `server.allowed_hosts` and `server.allowed_origins` as before. TLS is rustls with the ring provider; openssl is not used.
|
||||
REST and `/mcp` are then served over HTTPS only. Replace the files and send `SIGHUP` to rotate without dropping connections (a bad pair keeps the old certificate). rustls only; no openssl. Self-signed example, rotation caveats, ACME and sops paths: [docs/tls.md](docs/tls.md).
|
||||
|
||||
Self-signed example:
|
||||
|
||||
```sh
|
||||
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes -days 365 \
|
||||
-keyout key.pem -out cert.pem -subj '/CN=monitor.lan' \
|
||||
-addext 'subjectAltName=DNS:monitor.lan,DNS:localhost,IP:127.0.0.1'
|
||||
curl --cacert cert.pem -H "Authorization: Bearer $TOKEN" https://localhost:1984/api/v1/systemd/units
|
||||
```
|
||||
|
||||
Rotation: replace the files and send `SIGHUP` (`kill -HUP $(pidof slinuxm)`, or `systemctl kill -s HUP <unit>`). New connections get the new certificate; established ones are not dropped. The certificate and key are read as two separate files, so rotation tooling must send SIGHUP only after BOTH are in place; if the pair is unreadable or mismatched (for example the cert was replaced but the key not yet), the old certificate stays, an error is logged, and you send SIGHUP again once the files are consistent. Any intermediate certificates must be in the `cert_file` chain. Both the TLS and the plain listener are HTTP/1.1 only, share one accept loop, cap concurrent connections at 1024 and close connections that send no request header within 30 seconds. SIGHUP is harmless when TLS is disabled (it is logged and ignored). For ACME, point `cert_file` and `key_file` at the client's output (for example certbot's `live/<name>/fullchain.pem` and `privkey.pem`, or the NixOS `security.acme` directory) and send SIGHUP from the renewal hook. For sops-nix or systemd `LoadCredential`, point at the decrypted or credential path (`/run/credentials/<unit>/...`) so the service user needs no access to the original key file.
|
||||
|
||||
## NixOS
|
||||
|
||||
@@ -241,4 +192,4 @@ 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/`.
|
||||
The integration tests in `tests/` start the real router on an ephemeral port with fake sources. Design notes live in [ARCHITECTURE.md](ARCHITECTURE.md); work tracking in [TODO.md](TODO.md); extended docs in [docs/](docs/README.md).
|
||||
Reference in new issue
Block a user