Module: Origin/Host allowlists from allowedHosts and the FQDN, credentials refreshed on reload so SIGHUP rotates the TLS cert, string cert/key paths kept out of the store, docker.enable asserts virtualisation.docker. VM test covers healthz, 401, token mint/revoke via sudo -u, /mcp, Origin 403, root refusal and a TLS node. Package skips two unit tests that need host state the sandbox lacks. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017WMgwyHQQU9cB4ruRDrKow
15 KiB
skyg-linux-tracker
A small, read-only monitor for a single Linux host. One binary, slinuxm, serves:
- a REST API (with Server-Sent Events for follow endpoints),
- an MCP server (Streamable HTTP) so agents can inspect the host,
- optional OpenTelemetry export (metrics and logs over OTLP).
Data sources are systemd (D-Bus), the journal (libsystemd) and the Docker Engine API (unix socket). Nothing here can start, stop or modify anything.
Quick start
Try it on your own machine in a minute. It needs no root and no install, and it keeps its token database in a temp directory.
devenv shell && cargo build --release # or just: cargo build --release with the prerequisites below
export SKYG_AUTH__DB_PATH=/tmp/slinuxm-demo/db.sqlite
BIN=target/release/slinuxm
TOKEN=$($BIN token create demo) # printed once, never stored in plaintext
$BIN serve & # http://127.0.0.1:1984, loopback only
curl -s http://127.0.0.1:1984/healthz # public
curl -s -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:1984/api/v1/systemd/units?state=failed'
curl -s -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:1984/api/v1/journal?priority=err&lines=20'
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:1984/api/v1/docker/ps # 503 if Docker is not running
Point an MCP client at http://127.0.0.1:1984/mcp with the same bearer header (see MCP). Stop the server with kill %1.
The service listens on loopback by default. To reach it from another machine set server.bind, keep auth on, and use TLS. For a permanent install as a systemd service, see Install and Tokens.
Build
devenv shell # toolchain, pkg-config, libsystemd, otelcol-contrib
cargo build --release # target/release/slinuxm
Without devenv you need a Rust toolchain, pkg-config and the libsystemd development files.
Install
sudo install -m 0755 target/release/slinuxm /usr/local/bin/slinuxm
sudo useradd --system --no-create-home --shell /usr/sbin/nologin skyg
sudo install -m 0644 config.example.toml /etc/skyg-linux-tracker.toml # then edit
sudo install -m 0644 systemd/skyg-linux-tracker.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now skyg-linux-tracker
The unit runs as the skyg user with SupplementaryGroups=systemd-journal and a private StateDirectory (/var/lib/skyg-linux-tracker, mode 0700) holding the token database. Its sandbox options are listed in the unit file.
Config
See config.example.toml; every value shown is the default. Precedence, lowest to highest: defaults, config file, SKYG_* environment variables (nesting with __, for example SKYG_SERVER__PORT), CLI flags. slinuxm --print-config prints the effective configuration with secrets redacted.
Startup refuses auth.enabled = false on a non-loopback server.bind.
Tokens
All /api/v1/* and /mcp requests need Authorization: Bearer <token>. /healthz is public. Tokens are stored hashed (sha256) in SQLite, and the plaintext is shown once.
Run the token CLI as the service user (the unit's User=skyg), i.e. sudo -u <service user> slinuxm token create <name>. The CLI refuses to run (with the matching sudo -u <owner> ... hint) when the effective uid, root included, does not own the database file or, if it does not exist yet, its existing state directory, so it cannot create or modify state owned by another user:
sudo -u skyg slinuxm token create my-laptop --config /etc/skyg-linux-tracker.toml
sudo -u skyg slinuxm token list --config /etc/skyg-linux-tracker.toml
sudo -u skyg slinuxm token revoke my-laptop --config /etc/skyg-linux-tracker.toml
Revocation takes effect immediately; no restart is needed.
Notes:
auth.db_pathmust stay under the unit'sStateDirectory(/var/lib/skyg-linux-tracker). The unit usesProtectSystem=strict, so any other location needs a matchingReadWritePaths=.token createneeds the state directory to exist, so start the service once first (systemd creates it with the right owner), then run the CLI asskyg.- A state directory the server creates itself is made 0700 and the database file 0600 from creation. An existing directory is never chmod'd; a group/world-accessible one only logs a warning.
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 |
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'
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):
{
"mcpServers": {
"linux-tracker": {
"url": "http://127.0.0.1:1984/mcp",
"headers": { "Authorization": "Bearer slinuxm_..." }
}
}
}
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:
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.
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):
[server.tls]
enabled = true
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.
Self-signed example:
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
The flake exports packages.<system>.default and nixosModules.default.
# flake.nix
inputs.skyg-linux-tracker.url = "github:<owner>/linux-system-monitor";
# in your nixosSystem modules
modules = [
skyg-linux-tracker.nixosModules.default
{ services.skyg-linux-tracker.enable = true; }
];
That runs the service as the skyg-linux-tracker user on 127.0.0.1:1984 with the same sandbox as systemd/skyg-linux-tracker.service, writes /etc/skyg-linux-tracker.toml (the path the CLI reads by default) and installs slinuxm system-wide. Mint the first token as the service user:
sudo -u skyg-linux-tracker slinuxm token create my-laptop
Options (under services.skyg-linux-tracker): port (1984), bind ("127.0.0.1"), tls.{enable,certFile,keyFile} (passed through LoadCredential, so the service user never reads the original key; systemctl reload skyg-linux-tracker re-reads them; for ACME add security.acme.certs.<name>.reloadServices = [ "skyg-linux-tracker" ]), openFirewall (all interfaces), firewallInterfaces (recommended for a LAN), allowedHosts, docker.enable (adds the root-equivalent docker group), settings (freeform TOML merged over the module defaults) and environmentFile (secrets such as SKYG_OTEL__HEADERS__AUTHORIZATION, kept out of the store and out of the generated TOML).
Exposure: keep the default loopback bind and reach it over Tailscale or a TLS reverse proxy. Bearer tokens over plain HTTP are readable on a LAN. A non-loopback bind with auth.enabled = false fails at evaluation time. For bind = "0.0.0.0" add the names clients use to allowedHosts (networking.hostName is added for you), and prefer firewallInterfaces = [ "enp3s0" ] over openFirewall.
services.skyg-linux-tracker = {
enable = true;
bind = "0.0.0.0";
firewallInterfaces = [ "enp3s0" ];
allowedHosts = [ "monitor.lan:1984" ];
tls = { enable = true; certFile = "/var/lib/acme/monitor.lan/fullchain.pem"; keyFile = "/var/lib/acme/monitor.lan/key.pem"; };
};
nix flake check runs a two-machine VM test (plain and TLS) covering healthz, 401, token mint and revoke through the CLI, /mcp and the Origin check.
Docker access
Reading the Docker socket directly requires group docker, which is root-equivalent. The unit file has this commented out. Prefer a read-only socket proxy that allows only GET /containers/*, /events and /version, for example tecnativa/docker-socket-proxy with CONTAINERS=1 EVENTS=1 POST=0, exposed as a unix socket (or loopback TCP through a socat bridge), then:
[sources]
docker_socket = "/run/docker-proxy/docker.sock"
A stock install does not add the docker group, so out of the box the Docker routes return 503 until you either grant access or configure a proxy. If the socket is missing or unreadable, Docker routes return 503 and everything else keeps working.
OpenTelemetry
[otel]
enabled = true
endpoint = "http://localhost:4317" # gRPC; or http://localhost:4318 with protocol = "http/protobuf"
export_logs = true
Metrics are polled every metrics_interval_secs (systemd unit active/failed/restarts and timer next elapse; container running/healthy/uptime/restarts). Logs fan out from the journal and from Docker containers. For a local collector with a debug exporter: devenv up (runs otelcol-contrib --config dev/otelcol.yaml). On SIGTERM pending records are flushed before exit.
Verifying a release binary
ldd /usr/local/bin/slinuxm # libc, libm, libgcc_s, libsystemd and its dependencies only
Testing
devenv shell -- smoke # same as: cargo test --test binary_smoke -- --nocapture
The smoke test runs the real built slinuxm binary against a throwaway SQLite database in a temp directory: it creates a token with the CLI, starts serve on a free loopback port, exercises /healthz, REST and MCP with and without the token, revokes the token, and checks a clean SIGTERM exit and a 0600 database. It needs no root and no network. Checks that depend on host data (systemd over D-Bus, the journal) are skipped with a printed reason when the source is unavailable; Docker is never required.
Development
cargo test
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/.