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

5.7 KiB
Raw Permalink Blame History

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.

  • 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.