144 lines
8.9 KiB
Markdown
144 lines
8.9 KiB
Markdown
# How it works
|
|
|
|
What the `slinuxm` binary is, what it does when it runs, and what it will never do. Read this first; the other guides assume it.
|
|
|
|
## One binary, one process
|
|
|
|
`slinuxm` is a single, self-contained executable. It does two kinds of work:
|
|
|
|
- **Run the server** (`slinuxm serve`, the default when no subcommand is given). A long-running process that answers HTTP requests about the host it runs on.
|
|
- **Run a one-shot command** (`slinuxm token ...`, `slinuxm peer ...`, `slinuxm openapi`, `--print-config`). These start, do one thing and exit. They never start a server.
|
|
|
|
There is no agent/daemon split, no separate database server and no web assets on disk: the REST API, the MCP server, the OpenTelemetry exporter and the `/docs` viewer are all inside the binary. Its only dynamic dependencies are libc, libm, libgcc_s and libsystemd.
|
|
|
|
## What the server reads
|
|
|
|
Everything is read **live, on each request**, from three sources on the local host:
|
|
|
|
| Source | How it is read | Needs |
|
|
| --- | --- | --- |
|
|
| systemd units and timers | D-Bus, system bus (`org.freedesktop.systemd1`) | nothing special; any user can read unit state |
|
|
| The journal | libsystemd (`sd-journal`) | membership of the `systemd-journal` group to see all logs |
|
|
| Docker containers and logs | Docker Engine API over a unix socket | access to the socket (see [Docker access](operations.md#docker-access)) |
|
|
|
|
Nothing is cached or collected in the background for REST or MCP. If Docker is not running, only the Docker routes fail (with `503`); everything else keeps working.
|
|
|
|
The only thing the server **stores** is a small SQLite database of API tokens (hashed). That database is the whole of its state.
|
|
|
|
## What it serves
|
|
|
|
All on one port (default `1984`, bound to `127.0.0.1` by default):
|
|
|
|
```text
|
|
client (curl, browser, MCP client, another slinuxm)
|
|
│ HTTP or HTTPS, HTTP/1.1
|
|
▼
|
|
┌───────────────────── slinuxm serve ─────────────────────┐
|
|
│ /healthz, /docs public, no host data │
|
|
│ │
|
|
│ bearer-token check ──► token database (SQLite) │
|
|
│ ├─ /api/v1/* REST, JSON, SSE for "follow" │
|
|
│ └─ /mcp MCP server (Streamable HTTP) │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ sources: systemd · journal · Docker │
|
|
│ │
|
|
│ optional background tasks: │
|
|
│ OTel exporter ──push──► your OTLP collector │
|
|
│ peer health checks ──► other slinuxm instances │
|
|
└─────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
- **REST API** under `/api/v1`: GET only. Lists and details for units, timers, journal entries and containers. "Follow" endpoints (journal, container logs) stream as Server-Sent Events. Full table: [api.md](api.md).
|
|
- **MCP server** at `/mcp`: the same data as tools, prompts and resources for AI agents. REST and MCP call the same code, so they always return the same data.
|
|
- **OpenTelemetry** (off by default): pushes unit and container status as metrics and journal and container logs as OTel logs to a collector you point it at. This is the one part that polls on a timer.
|
|
- **`/healthz`**: public liveness check with the version.
|
|
- **`/docs`**: a built-in API viewer (Redoc). The page is public; it asks for a token before it fetches the API description.
|
|
- **Peers** (off by default): one instance can health-check other `slinuxm` instances and pass read-only requests through to them. See [consolidator.md](consolidator.md).
|
|
|
|
## Read-only by design
|
|
|
|
No code path can start, stop, restart or modify a unit, a container or a file outside the state directory. Every route is GET. The only writes the binary ever makes are to its own token database. This is why it is safe to hand a token to an AI agent.
|
|
|
|
Log text from the journal and from containers is produced by other programs. It is returned as untrusted data and labelled as such to MCP clients.
|
|
|
|
## Authentication
|
|
|
|
Every request to `/api/v1/*` and `/mcp` must carry `Authorization: Bearer <token>`.
|
|
|
|
- You create tokens with `slinuxm token create <name>`. The plaintext is printed **once**; only a sha256 hash is stored.
|
|
- On each request the server hashes the presented token and looks it up. Revoking or rotating a token takes effect on the next request; no restart.
|
|
- A missing or wrong token gets `401` with `WWW-Authenticate: Bearer`, the same for REST and MCP.
|
|
- Every token can read everything. There are no scopes.
|
|
|
|
Auth can be switched off (`auth.enabled = false`), but only while the server listens on loopback; startup refuses otherwise.
|
|
|
|
## Lifecycle of `slinuxm serve`
|
|
|
|
1. **Load configuration**: built-in defaults, then the config file, then `SKYG_*` environment variables, then CLI flags (later wins). Invalid combinations stop here with an error. See [configuration.md](configuration.md).
|
|
2. **Check peer token files** (only when peers are enabled).
|
|
3. **Start telemetry**: logging to stderr, plus OTLP exporters when `otel.enabled`.
|
|
4. **Open the token database** (when auth is on), creating it if needed: directory mode 0700, file mode 0600.
|
|
5. **Load the TLS certificate and key** (when TLS is on). A missing or mismatched pair stops startup.
|
|
6. **Bind the listener**. Connections are capped at 1024; a connection that sends no request within 30 s is closed.
|
|
7. **Start background tasks**: OTel exporters and peer health checks, if enabled.
|
|
8. **Serve** until a stop signal.
|
|
|
|
Logs go to stderr, so under systemd they land in the journal (`journalctl -u skyg-linux-tracker`).
|
|
|
|
## Signals
|
|
|
|
| Signal | Effect |
|
|
| --- | --- |
|
|
| `SIGTERM` / `SIGINT` | Graceful stop: stop accepting, end open SSE streams, drain requests (at most 10 s), stop exporters (at most 10 s), flush OTel, close the database. A systemd stop timeout of 30 s covers all of it. |
|
|
| `SIGHUP` | Reload without dropping connections: re-reads the TLS certificate and key, and the `[peers]` section. A bad new certificate pair is rejected and the old one kept. Everything else (port, bind, auth, sources, OTel, limits) needs a restart. |
|
|
|
|
## Commands
|
|
|
|
```text
|
|
slinuxm [GLOBAL OPTIONS] [COMMAND]
|
|
|
|
Commands:
|
|
serve Run the server (default when no command is given)
|
|
token create <name> Create a token and print it once
|
|
token list List tokens: name, created, revoked, last used (never the secret)
|
|
token revoke <name> Revoke a token; effective immediately
|
|
token rotate <name> Replace a token's secret, print the new one once; re-enables a revoked token
|
|
peer list List configured peers (config only)
|
|
peer check <name> Probe one peer once over TCP and the authenticated API
|
|
openapi [--peers] Print the OpenAPI description and exit (reads no config)
|
|
|
|
Global options:
|
|
--config <FILE> Config file (default /etc/skyg-linux-tracker.toml if present; env SKYG_CONFIG)
|
|
--print-config Print the effective configuration, secrets redacted, and exit
|
|
--bind <IP> server.bind
|
|
--port <PORT> server.port
|
|
--auth-enabled <BOOL> auth.enabled
|
|
--db-path <FILE> auth.db_path
|
|
--docker-socket <FILE> sources.docker_socket
|
|
--journal-namespace <NAME> sources.journal_namespace
|
|
--otel-enabled <BOOL> otel.enabled
|
|
--otel-endpoint <URL> otel.endpoint
|
|
--version Print the build version (YYYY.MM.DD-<branch>-<sha>)
|
|
```
|
|
|
|
`token` commands open the token database directly, so they must run **as the user that owns it**, normally the service user (`sudo -u <service user> slinuxm token ...`). They refuse to run as anyone else, root included, and print the right `sudo -u` command. This prevents root from creating database files the service can no longer open.
|
|
|
|
## Files it touches
|
|
|
|
| Path | Purpose | Default |
|
|
| --- | --- | --- |
|
|
| Config file | read at start (and the `[peers]` section on SIGHUP) | `/etc/skyg-linux-tracker.toml` |
|
|
| Token database | read and written | `/var/lib/skyg-linux-tracker/db.sqlite` |
|
|
| TLS certificate and key | read at start and on SIGHUP | none (TLS off) |
|
|
| Docker socket | read | `/var/run/docker.sock` |
|
|
| Peer token files | read on every peer check and request | none (peers off) |
|
|
|
|
## Where to go next
|
|
|
|
- Install it: [install.md](install.md)
|
|
- Configure it: [configuration.md](configuration.md)
|
|
- Run it day to day (tokens, network exposure, Docker, OTel, troubleshooting): [operations.md](operations.md)
|
|
- Every route and MCP tool: [api.md](api.md)
|
|
- Internals and design decisions: [ARCHITECTURE.md](../ARCHITECTURE.md)
|