Files
2026-10-19 14:16:09 -04:00

66 lines
5.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# WS-H — NixOS module + package
| Field | Value |
|---|---|
| Status | Done |
| 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.<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**, 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 <name>`; 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.<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 -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), `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.
- 2026-10-19: **Gate passed.** `nix build .#default` exit 0 (17 min, remote builder): `bin/slinuxm` 24 MB; `ldd` lists only libsystemd, libgcc_s, libm, libc and the loader, no ssl/crypto library (the string `openssl` in the binary is ring's bundled asm banners, not a dependency). `nix flake check` exit 0 with KVM: `nixosModules.default`, `packages`, `checks.package` and `checks.vm` pass; the VM test's 7 subtests pass (plain: healthz public + API 401, token minted via `sudo -u` system CLI, `/mcp` initialize + tools/list, bad Origin rejected, revoke without restart, root refused by token CLI; TLS: HTTPS healthz, plain HTTP refused, token works). aarch64-linux skipped (incompatible; `--all-systems` would include it). Harmless noise: post-build-hook cache-push 404 to the local binary cache. The fresh-host criterion is met by the VM test; deployment on a real host (minipc1) is not confirmed to use this module.