Files
skyg-linux-tracker/plan/workstreams/WS-H-nixos.md
T

63 lines
4.1 KiB
Markdown

# 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) |
| 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.<system>.default` and `nixosModules.default`, plus `checks` wired to H8.
- **H3** `nix/module.nix` options under `services.skyg-linux-tracker`:
- `enable`, `package`
- `port` (default **1984**; the app default is unchanged, DEC-9)
- `bind` (default `"127.0.0.1"`)
- `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 ]`. A thin wrapper on `PATH` re-execs `slinuxm token create|list|revoke …` as the service user via `sudo -u`, and passes every other subcommand through untouched. Without privileges it prints a clear message instead of a permission error (DEC-10).
- **H6** Firewall: `openFirewall` opens the port globally. Also support an interface-scoped option (`networking.firewall.interfaces.<if>.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 slinuxm token create <name>`), 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
2. `/api/v1/systemd/units` returns 401 without a token
3. `sudo 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. `sudo slinuxm token revoke t` 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 set in the module only, so the non-Nix path is unchanged.
- Declarative/hash-imported tokens and activation-time `bootstrapTokens` are out of scope for v1 (DEC-11). They would need a `slinuxm` change to import hashes from a file.
- The module must not put secrets in the generated TOML. Anything sensitive goes through `environmentFile`.
## Log
- 2026-10-15: Card created from design discussion.