F: F4 peers docs, agenix example and tool-count note
README peers section, docs/consolidator.md (threat model, tokens, firewall, worked agenix example, reload/restart), the MCP tool count in both tables, and config.example.toml commentary.
This commit is contained in:
1 parent
66ee41a672
commit
4d83c2eff5
7 files changed
+301
-20
No files matched your search
@@ -91,7 +91,7 @@ Full route table with parameters: [docs/api.md](docs/api.md).
|
||||
|
||||
## MCP
|
||||
|
||||
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.
|
||||
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. A [consolidator](#peers-consolidator) adds `list_peers` and `get_peer` and a `peer` argument on every tool, for ten tools. 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"`.
|
||||
|
||||
@@ -110,6 +110,57 @@ key_file = "/etc/skyg/tls/key.pem" # PEM, PKCS#8, PKCS#1 or SEC1
|
||||
|
||||
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).
|
||||
|
||||
## Peers (consolidator)
|
||||
|
||||
One `slinuxm` can watch other instances: declare them as **peers** and it health-checks each one and passes read-only requests through to it, so one MCP endpoint or one REST base URL covers the fleet. Off by default; a peer-less instance keeps exactly the same routes, eight MCP tools, metrics and background tasks as before.
|
||||
|
||||
```toml
|
||||
[peers]
|
||||
enabled = true # other intervals, timeouts and caps: config.example.toml
|
||||
|
||||
[[peers.peer]]
|
||||
name = "minipc1" # ^[a-z0-9][a-z0-9_-]{0,31}$, at most 64 peers
|
||||
url = "https://minipc1:1984" # http:// to a non-loopback host also needs allow_plain_http = true
|
||||
token_file = "/run/credentials/skyg-linux-tracker.service/peer-minipc1"
|
||||
ca_file = "/etc/skyg/private-ca.pem" # optional extra trust anchor
|
||||
|
||||
[[peers.peer]]
|
||||
name = "nas"
|
||||
url = "http://nas:1984"
|
||||
token_file = "/etc/skyg/peer-nas.token" # 0600, owned by the service user
|
||||
allow_plain_http = true
|
||||
```
|
||||
|
||||
`token_file` holds a path, never the token. A consolidator has to replay the peer's plaintext bearer token, so the token lives in a file managed outside `slinuxm` (agenix on NixOS), is read into memory on every check and request, and never appears in the config, `--print-config`, the database or the logs. Mint **one token per consolidator on every peer** and use it only there (`sudo -u <service user> slinuxm token create consolidator-<host>`), so a single `token revoke` on a peer cuts that consolidator off and nothing else. Replacing the file is enough to rotate: no restart.
|
||||
|
||||
Two checks per peer, kept in memory and reset on restart:
|
||||
|
||||
- **server**: a TCP connect to the peer's port.
|
||||
- **API**: an authenticated `GET /api/v1/ping`. A `401` means the API runs and our token does not: `api.up = true` with `api.auth = "rejected"`. That is reported to you as a `503` naming the peer, never as a `401` that would suggest re-authenticating with this host. A peer without the ping route falls back to public `/healthz` and reports `api.auth = "unknown"`.
|
||||
|
||||
```sh
|
||||
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:1984/api/v1/peers
|
||||
curl -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:1984/api/v1/peers/minipc1/systemd/units?state=failed'
|
||||
sudo -u skyg slinuxm peer list --config /etc/skyg-linux-tracker.toml
|
||||
sudo -u skyg slinuxm peer check minipc1 --config /etc/skyg-linux-tracker.toml
|
||||
```
|
||||
|
||||
`GET /api/v1/peers` lists every peer, `GET /api/v1/peers/{peer}` one of them. `GET /api/v1/peers/{peer}/...` is a GET-only, allowlisted pass-through (`systemd/...`, `journal`, `journal/follow`, `docker/...`): the peer's answer comes back unchanged with `x-slinuxm-peer: <peer>`, a peer that is down, rejects our token or times out is a `503` naming it, `x-slinuxm-hop` from a caller is a `400`, and unknown peers are a `404`. With peers enabled MCP grows `list_peers` and `get_peer`, and every other tool accepts an optional `peer` argument (ten tools instead of eight). There is no aggregation across peers in this version: ask one peer at a time. OTel gains `peer.up`, `peer.api.auth_ok`, `peer.check.duration_seconds` and `peer.last_change_timestamp_seconds`.
|
||||
|
||||
On NixOS the module declares peers and delivers each token through systemd `LoadCredential`, so the service user never needs to read the agenix output:
|
||||
|
||||
```nix
|
||||
services.skyg-linux-tracker.peers = {
|
||||
enable = true;
|
||||
peers.minipc1 = {
|
||||
url = "https://minipc1:1984";
|
||||
tokenFile = config.age.secrets.peer-minipc1.path; # a string path, never a path literal
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Worked agenix setup, the threat model, the firewall note (every peer must accept the consolidator's address on its port), reload and shutdown semantics: [docs/consolidator.md](docs/consolidator.md). The peers tests are `tests/peers.rs` (in-process, no VM) and the three-machine NixOS VM test: `devenv shell -- dev-test integration peers`, and for the VM test `devenv shell -- dev-test vm peers`, which is `nix build .#checks.x86_64-linux.vm-peers -L`.
|
||||
|
||||
|
||||
## NixOS
|
||||
|
||||
|
||||
Reference in new issue
Block a user