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

4.1 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)
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; 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.