From cfb3a400df0efc786908fb4661ecbb0c1cf0193c Mon Sep 17 00:00:00 2001 From: ari Date: Mon, 19 Oct 2026 20:58:26 -0400 Subject: [PATCH] C: document proxied unit names, status mapping and peer header rules --- docs/api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api.md b/docs/api.md index de66ebb..9441c3e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -43,11 +43,11 @@ Present only when `[peers] enabled = true`. The same inbound token as the rest o `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 : 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}/logs`. `ping` and `peers/...` are not forwarded. `..`, encoded slashes and any other path are `400` `peer : 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 : unsupported query parameter`. The caller's `Authorization` and `Cookie` are not forwarded; the consolidator sends the peer's own token. +`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}/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 : 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 : unsupported query parameter`. 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 : chained requests are not allowed`. Other methods are `405`. `journal/follow` and docker logs with `follow=1` are `text/event-stream`, cut off at `limits.max_follow_secs` or shutdown. Bodies larger than `peers.max_response_bytes` are `503` `peer : oversize`. +A request that already has `x-slinuxm-hop` is `400` `peer : 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 : 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_`), so a redirect or the peer's own error body never reaches the caller. -Every proxied response, including the consolidator's own errors for that peer (`400`, `404`, `500`, `503`), carries `x-slinuxm-peer: `. +Every proxied response for a configured peer, including the consolidator's own errors (`400`, `404`, `500`, `503`), carries `x-slinuxm-peer: `. 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 : peer rejected credentials`, so the caller does not re-authenticate against the wrong host.