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

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