Files
2026-10-21 00:12:33 -04:00

8.9 KiB

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)

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):

            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.
  • 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.

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.
  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

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