4.5 KiB
4.5 KiB
WS-H — NixOS module + package
| Field | Value |
|---|---|
| Status | Backlog |
| Owner | — |
| Phase | 4 (single track, after release candidate) |
| Depends on | P3 (final unit hardening, --print-config, README); WS-I (TLS options) |
| Blocks | — |
| Owned files | flake.nix, nix/package.nix, nix/module.nix, nix/tests/, README.md (NixOS section only) |
Goal
Install skyg-linux-tracker on NixOS as a systemd service that exposes the REST API and /mcp on port 1984, and install the slinuxm CLI system-wide so the operator can mint the first token.
Tasks
Tick these in TODO.md.
- H1
nix/package.nix:rustPlatform.buildRustPackagefrom the committedCargo.lock.nativeBuildInputs = [ pkg-config cmake ](cmake foraws-lc-sys),buildInputs = [ systemd ]. Binary isslinuxm. Live-journal tests are#[ignore], so the sandbox build runscargo test. - H2
flake.nixexportingpackages.<system>.defaultandnixosModules.default, pluscheckswired to H8. - H3
nix/module.nixoptions underservices.skyg-linux-tracker:enable,packageport(default 1984; the app default is unchanged, DEC-9)bind(default"127.0.0.1"; LAN exposure is set per install)tls.enable,tls.certFile,tls.keyFile(passed via systemdLoadCredential, DEC-12)openFirewall(defaultfalse)allowedHosts(extra Host/Origin entries for/mcp; the module addsnetworking.hostNameautomatically)docker.enable(defaultfalse; adds thedockergroup and sets the socket path, DEC-6)settings(freeform TOML viapkgs.formats.toml, merged over module defaults)environmentFile(for secrets such asSKYG_OTEL__HEADERS__*, kept out of the store)
- H4 Service definition:
- dedicated user and group
StateDirectory=skyg-linux-tracker, mode 0700 (matchesdb_path)SupplementaryGroups=systemd-journal(plusdockerwhen enabled)- the P3 hardening set (
NoNewPrivileges,ProtectSystem=strict,ProtectHome,PrivateTmp,RestrictAddressFamilies, …), reusingsystemd/skyg-linux-tracker.servicerather than diverging - config written to
/etc/skyg-linux-tracker.toml, the default path the app already reads, so the CLI and the service always agree
- H5 CLI install (required):
environment.systemPackages = [ cfg.package ], plain binary, no wrapper (DEC-10). Mint tokens withsudo -u skyg-linux-tracker slinuxm token create <name>; the module's NixOS notes and the README show this exact command. The root guard inslinuxm(token commands refuse to run as root against another user's DB and print the command above) is implemented here as a small change in the CLI code. - H6 Firewall:
openFirewallopens the port globally. Also support an interface-scoped option (networking.firewall.interfaces.<if>.allowedTCPPorts), which is the recommended LAN setup. Assert at eval time thatbindnon-loopback is accompanied by auth enabled. - H7 README NixOS section: flake input, minimal config, token workflow (
sudo -u skyg-linux-tracker slinuxm token create <name>), the exposure model (loopback + Tailscale or TLS proxy recommended, since bearer tokens over plain HTTP are readable on a LAN),allowedHostsforbind = 0.0.0.0. - H8 NixOS VM test (
nix/tests/):- service starts and
curl :1984/healthzreturns 200 unauthenticated (a second case with TLS enabled and a test cert) /api/v1/systemd/unitsreturns 401 without a tokensudo -u skyg-linux-tracker slinuxm token create tprints a token, and the same request with it returns 200/mcpinitialize and tools/list work with the tokenslinuxm token revoke t(samesudo -uform) makes the same request return 401 without a restart- bad Origin on
/mcpreturns 403
- service starts and
Done when
nix build .#defaultproducesbin/slinuxm, andlddshows only libc and libsystemd (plus deps). No openssl.nix flake checkpasses, including the VM test (H8).- On a NixOS host, enabling the module with
port = 1984exposes:1984as described, andslinuxm token createworks from a normal login shell.
Notes
- Port 1984 is set in the module only, so the non-Nix path is unchanged.
- Tokens are printed once and never stored (DEC-11). Declarative/hash-imported tokens and activation-time
bootstrapTokensare out of scope for v1 are not offered. - The module must not put secrets in the generated TOML. Anything sensitive goes through
environmentFile.
Log
- 2026-10-15: Card created from design discussion.