# WS-H — NixOS module + package | Field | Value | |---|---| | Status | Review (gate outstanding) | | Owner | Ari | | 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`](../../TODO.md). - **H1** `nix/package.nix`: `rustPlatform.buildRustPackage` from the committed `Cargo.lock`. `nativeBuildInputs = [ pkg-config cmake ]` (cmake for `aws-lc-sys`), `buildInputs = [ systemd ]`. Binary is `slinuxm`. Live-journal tests are `#[ignore]`, so the sandbox build runs `cargo test`. - **H2** `flake.nix` exporting `packages..default` and `nixosModules.default`, plus `checks` wired to H8. - **H3** `nix/module.nix` options under `services.skyg-linux-tracker`: - `enable`, `package` - `port` (default **1984**, same as the binary default) - `bind` (default `"127.0.0.1"`; LAN exposure is set per install) - `tls.enable`, `tls.certFile`, `tls.keyFile` (passed via systemd `LoadCredential`, DEC-12) - `openFirewall` (default `false`) - `allowedHosts` (extra Host/Origin entries for `/mcp`; the module adds `networking.hostName` automatically) - `docker.enable` (default `false`; adds the `docker` group and sets the socket path, DEC-6) - `settings` (freeform TOML via `pkgs.formats.toml`, merged over module defaults) - `environmentFile` (for secrets such as `SKYG_OTEL__HEADERS__*`, kept out of the store) - **H4** Service definition: - dedicated user and group - `StateDirectory=skyg-linux-tracker`, mode 0700 (matches `db_path`) - `SupplementaryGroups=systemd-journal` (plus `docker` when enabled) - the P3 hardening set (`NoNewPrivileges`, `ProtectSystem=strict`, `ProtectHome`, `PrivateTmp`, `RestrictAddressFamilies`, …), reusing `systemd/skyg-linux-tracker.service` rather 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 with `sudo -u skyg-linux-tracker slinuxm token create `; the module's NixOS notes and the README show this exact command. The root guard in `slinuxm` (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: `openFirewall` opens the port globally. Also support an interface-scoped option (`networking.firewall.interfaces..allowedTCPPorts`), which is the recommended LAN setup. Assert at eval time that `bind` non-loopback is accompanied by auth enabled. - **H7** README NixOS section: flake input, minimal config, token workflow (`sudo -u skyg-linux-tracker slinuxm token create `), the exposure model (loopback + Tailscale or TLS proxy recommended, since bearer tokens over plain HTTP are readable on a LAN), `allowedHosts` for `bind = 0.0.0.0`. - **H8** NixOS VM test (`nix/tests/`): 1. service starts and `curl :1984/healthz` returns 200 unauthenticated (a second case with TLS enabled and a test cert) 2. `/api/v1/systemd/units` returns 401 without a token 3. `sudo -u skyg-linux-tracker slinuxm token create t` prints a token, and the same request with it returns 200 4. `/mcp` initialize and tools/list work with the token 5. `slinuxm token revoke t` (same `sudo -u` form) makes the same request return 401 without a restart 6. bad Origin on `/mcp` returns 403 ## Done when - `nix build .#default` produces `bin/slinuxm`, and `ldd` shows only libc and libsystemd (plus deps). No openssl. - `nix flake check` passes, including the VM test (H8). - On a NixOS host, enabling the module with `port = 1984` exposes `:1984` as described, and `slinuxm token create` works from a normal login shell. ## Notes - Port 1984 is also the binary default, so the module just passes it through. - Tokens are printed once and never stored (DEC-11). Declarative/hash-imported tokens and activation-time `bootstrapTokens` are out of scope for v1 and 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. - 2026-10-19: Merged to `main` as PR #1 (34da657): `nix/package.nix`, `nix/module.nix`, `flake.nix`, `nix/tests/vm.nix`, and the README NixOS section. H1–H8 ticked in `TODO.md`. **Only the Gate remains** (`nix build`, `nix flake check` incl. the VM test, `ldd` check); it is being run and the result will be logged here. Card stays in Review until then. - _WS-H gate result (`nix build`, `nix flake check` incl. VM test, `ldd`): pending. Append it here, then update the In progress / Review row and milestone M4 in [`TODO.md`](../../TODO.md)._