5.7 KiB
5.7 KiB
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.buildRustPackagefrom the committedCargo.lock.nativeBuildInputs = [ pkg-config cmake ](cmake foraws-lc-sys),buildInputs = [ systemd ]. Binary isslinuxm. Live-journal tests are#[ignore], so the sandbox build runscargo test. - H2
flake.nixexportingpackages.<system>.defaultandnixosModules.default, pluscheckswired to H8. - H3
nix/module.nixoptions underservices.skyg-linux-tracker:enable,packageport(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 systemdLoadCredential, DEC-12)openFirewall(defaultfalse)allowedHosts(extra Host/Origin entries for/mcp; the module addsnetworking.hostNameautomatically)docker.enable(defaultfalse; adds thedockergroup and sets the socket path, DEC-6)settings(freeform TOML viapkgs.formats.toml, merged over module defaults)environmentFile(for secrets such asSKYG_OTEL__HEADERS__*, kept out of the store)
- H4 Service definition:
- dedicated user and group
StateDirectory=skyg-linux-tracker, mode 0700 (matchesdb_path)SupplementaryGroups=systemd-journal(plusdockerwhen enabled)- the P3 hardening set (
NoNewPrivileges,ProtectSystem=strict,ProtectHome,PrivateTmp,RestrictAddressFamilies, …), reusingsystemd/skyg-linux-tracker.servicerather 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 withsudo -u skyg-linux-tracker slinuxm token create <name>; the module's NixOS notes and the README show this exact command. The root guard inslinuxm(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:
openFirewallopens the port globally. Also support an interface-scoped option (networking.firewall.interfaces.<if>.allowedTCPPorts), which is the recommended LAN setup. Assert at eval time thatbindnon-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),allowedHostsforbind = 0.0.0.0. - H8 NixOS VM test (
nix/tests/):- service starts and
curl :1984/healthzreturns 200 unauthenticated (a second case with TLS enabled and a test cert) /api/v1/systemd/unitsreturns 401 without a tokensudo -u skyg-linux-tracker slinuxm token create tprints a token, and the same request with it returns 200/mcpinitialize and tools/list work with the tokenslinuxm token revoke t(samesudo -uform) makes the same request return 401 without a restart- bad Origin on
/mcpreturns 403
- service starts and
Done when
nix build .#defaultproducesbin/slinuxm, andlddshows only libc and libsystemd (plus deps). No openssl.nix flake checkpasses, including the VM test (H8).- On a NixOS host, enabling the module with
port = 1984exposes:1984as described, andslinuxm token createworks 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
bootstrapTokensare 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
mainas PR #1 (34da657):nix/package.nix,nix/module.nix,flake.nix,nix/tests/vm.nix, and the README NixOS section. H1–H8 ticked inTODO.md. Only the Gate remains (nix build,nix flake checkincl. the VM test,lddcheck); it is being run and the result will be logged here. Card stays in Review until then. - 2026-10-19: Gate passed.
nix build .#defaultexit 0 (17 min, remote builder):bin/slinuxm24 MB;lddlists only libsystemd, libgcc_s, libm, libc and the loader, no ssl/crypto library (the stringopensslin the binary is ring's bundled asm banners, not a dependency).nix flake checkexit 0 with KVM:nixosModules.default,packages,checks.packageandchecks.vmpass; the VM test's 7 subtests pass (plain: healthz public + API 401, token minted viasudo -usystem CLI,/mcpinitialize + 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-systemswould 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.