From e6cb4c0b3efc0f0aad425ac4ab7aaa9fa3b37a60 Mon Sep 17 00:00:00 2001 From: ari Date: Mon, 19 Oct 2026 23:08:04 -0400 Subject: [PATCH] F: F1 NixOS peers options with LoadCredential token delivery --- nix/module.nix | 148 +++++++++++++++++++++++++++++-- nix/tests/module-peers.nix | 173 +++++++++++++++++++++++++++++++++++++ 2 files changed, 314 insertions(+), 7 deletions(-) create mode 100644 nix/tests/module-peers.nix diff --git a/nix/module.nix b/nix/module.nix index 6782435..5b7e086 100644 --- a/nix/module.nix +++ b/nix/module.nix @@ -2,7 +2,7 @@ let cfg = config.services.skyg-linux-tracker; - inherit (lib) mkOption mkEnableOption mkIf types; + inherit (lib) mkOption mkEnableOption mkIf mkMerge types; name = "skyg-linux-tracker"; credDir = "/run/credentials/${name}.service"; @@ -35,8 +35,38 @@ let auth.db_path = "/var/lib/${name}/db.sqlite"; } // lib.optionalAttrs cfg.docker.enable { sources.docker_socket = "/var/run/docker.sock"; + } // lib.optionalAttrs (cfg.peers.enable || cfg.peers.settings != { } || cfg.peers.peers != { }) { + peers = peersSection; }; + # Declared peers that stay in the rendered config. A peer with `enable = + # false` is left out entirely: no credential is shipped for it, and the + # service refuses to start while an enabled peer's token file is missing. + enabledPeerNames = lib.attrNames (lib.filterAttrs (_: peer: peer.enable) cfg.peers.peers); + + # The config file holds paths only. Each peer reads its bearer token from + # the credential directory, which systemd populates from `tokenFile`, so + # the service user never needs access to the agenix output. + renderedPeers = map ( + peerName: + { + name = peerName; + url = cfg.peers.peers.${peerName}.url; + token_file = "${credDir}/peer-${peerName}"; + allow_plain_http = cfg.peers.peers.${peerName}.allowPlainHttp; + } + // lib.optionalAttrs (cfg.peers.peers.${peerName}.caFile != null) { + ca_file = cfg.peers.peers.${peerName}.caFile; + } + ) enabledPeerNames; + + # Only rendered when the feature is in use, so a peer-less deployment keeps + # the same generated config as before. + peersSection = + { enabled = cfg.peers.enable; } + // cfg.peers.settings + // lib.optionalAttrs (renderedPeers != [ ]) { peer = renderedPeers; }; + settings = lib.recursiveUpdate moduleDefaults cfg.settings; configFile = toml.generate "${name}.toml" settings; @@ -44,6 +74,17 @@ let bind = settings.server.bind; authEnabled = settings.auth.enabled or true; isLoopback = a: lib.hasPrefix "127." a || a == "::1"; + + # Names become file names and TOML keys; the regex is the one the binary + # enforces, so a bad name fails at build time instead of at startup. + validPeerName = n: builtins.match "[a-z0-9][a-z0-9_-]{0,31}" n != null; + # A path literal is rejected by the string type; an interpolated one + # (`"${./secret}"`) becomes a store path. Reject that too: a token in the + # store would defeat the whole credential scheme. + outsideStore = p: !lib.hasPrefix "${builtins.storeDir}/" p; + peerTokenOk = peer: + lib.hasPrefix "/" peer.tokenFile && outsideStore peer.tokenFile; + freeformPeers = cfg.settings.peers.peer or [ ]; in { options.services.skyg-linux-tracker = { @@ -122,6 +163,62 @@ in example = "/run/secrets/skyg-linux-tracker.env"; description = "systemd EnvironmentFile for secrets such as `SKYG_OTEL__HEADERS__AUTHORIZATION`, kept out of the store."; }; + + peers = { + enable = mkEnableOption "the consolidator (health checks and GET proxying to the peers declared below)"; + + settings = mkOption { + type = toml.type; + default = { }; + example = { tcp_interval_secs = 10; api_interval_secs = 30; fail_threshold = 2; }; + description = '' + Freeform `[peers]` tuning (snake_case keys as in config.example.toml), + merged over the defaults. Never put a token here: secrets come from + `peers.peers..tokenFile`. + ''; + }; + + peers = mkOption { + type = types.attrsOf (types.submodule { + options = { + url = mkOption { + type = types.str; + example = "https://minipc1:1984"; + description = "Base URL of the peer. `http` to a non-loopback host also needs `allowPlainHttp`."; + }; + tokenFile = mkOption { + type = types.str; + example = "/run/agenix/peer-minipc1"; + description = '' + Path of a file holding this peer's bearer token, normally + `config.age.secrets..path`. Must be an absolute path + outside the Nix store: the file is passed to the service with + systemd `LoadCredential`, so the token never enters the store, + the generated config or the service user's readable files. + ''; + }; + caFile = mkOption { + type = types.nullOr types.str; + default = null; + example = "/etc/ssl/private-ca.pem"; + description = "Optional PEM CA bundle used to verify this peer's TLS certificate."; + }; + enable = mkOption { + type = types.bool; + default = true; + description = "Set to false to keep the declaration without contacting the peer."; + }; + allowPlainHttp = mkOption { + type = types.bool; + default = false; + description = "Allow plain http to a non-loopback host. The bearer token travels in cleartext."; + }; + }; + }); + default = { }; + description = "Peers this instance consolidates, keyed by peer name (`^[a-z0-9][a-z0-9_-]{0,31}$`)."; + }; + }; }; config = mkIf cfg.enable { @@ -138,6 +235,32 @@ in assertion = !cfg.tls.enable || (cfg.tls.certFile != null && cfg.tls.keyFile != null); message = "services.skyg-linux-tracker.tls.enable requires tls.certFile and tls.keyFile."; } + { + assertion = cfg.peers.peers == { } || cfg.peers.enable; + message = "services.skyg-linux-tracker.peers.peers. requires peers.enable = true."; + } + { + assertion = !cfg.peers.enable || cfg.peers.peers != { } || freeformPeers != [ ]; + message = "services.skyg-linux-tracker.peers.enable requires at least one peer under peers.peers.."; + } + { + assertion = cfg.peers.peers == { } || !((cfg.settings.peers or { }) ? peer); + message = "services.skyg-linux-tracker: declare peers with peers.peers., not settings.peers.peer."; + } + { + # Option attribute names are unique by construction, so only the + # character set needs checking. + assertion = lib.all validPeerName (lib.attrNames cfg.peers.peers); + message = "services.skyg-linux-tracker.peers.peers.: names must match ^[a-z0-9][a-z0-9_-]{0,31}$."; + } + { + assertion = lib.all peerTokenOk (lib.attrValues cfg.peers.peers); + message = "services.skyg-linux-tracker.peers.peers..tokenFile must be an absolute path outside the Nix store (use config.age.secrets..path)."; + } + { + assertion = lib.all (peer: peer.caFile == null || lib.hasPrefix "/" peer.caFile) (lib.attrValues cfg.peers.peers); + message = "services.skyg-linux-tracker.peers.peers..caFile must be an absolute path when set."; + } ]; users.users.${name} = { @@ -167,15 +290,21 @@ in description = "skyg-linux-tracker: read-only systemd, journal and Docker monitor (REST, MCP, OTel)"; wantedBy = [ "multi-user.target" ]; after = [ "network.target" ] ++ lib.optional cfg.docker.enable "docker.service"; - restartTriggers = [ configFile ]; + # A peer (or TLS) change only needs SIGHUP: the server re-reads those + # from the config file. SIGHUP cannot re-bind the listener or reopen the + # database, so such changes need `systemctl restart` by hand. Changes to + # the unit itself (package, credential paths) still restart. + restartTriggers = lib.optional (!cfg.peers.enable) configFile; + reloadTriggers = lib.optional cfg.peers.enable configFile; # Mirrors systemd/skyg-linux-tracker.service; keep the two in step. serviceConfig = { Type = "simple"; ExecStart = "${lib.getExe cfg.package} serve --config /etc/${name}.toml"; ExecReload = "${pkgs.coreutils}/bin/kill -HUP $MAINPID"; - # Credentials are copied at start; refresh them so a reload rotates the cert. - RefreshOnReload = mkIf cfg.tls.enable "credentials"; + # Credentials are copied at start; refresh them so a reload rotates + # the certificate and the peer tokens. + RefreshOnReload = mkIf (cfg.tls.enable || cfg.peers.enable) "credentials"; Restart = "on-failure"; RestartSec = 5; TimeoutStopSec = 30; @@ -186,9 +315,14 @@ in StateDirectory = name; StateDirectoryMode = "0700"; EnvironmentFile = mkIf (cfg.environmentFile != null) cfg.environmentFile; - LoadCredential = mkIf cfg.tls.enable [ - "cert:${toString cfg.tls.certFile}" - "key:${toString cfg.tls.keyFile}" + LoadCredential = mkMerge [ + (mkIf cfg.tls.enable [ + "cert:${toString cfg.tls.certFile}" + "key:${toString cfg.tls.keyFile}" + ]) + (mkIf cfg.peers.enable (map ( + peerName: "peer-${peerName}:${cfg.peers.peers.${peerName}.tokenFile}" + ) enabledPeerNames)) ]; NoNewPrivileges = true; diff --git a/nix/tests/module-peers.nix b/nix/tests/module-peers.nix new file mode 100644 index 0000000..5a3a4d4 --- /dev/null +++ b/nix/tests/module-peers.nix @@ -0,0 +1,173 @@ +{ pkgs, module }: + +# Evaluation tests for the peers options of nix/module.nix. They render the +# configuration and the unit without building anything, which is why they run +# on any machine: `nix eval` only forces the values below. +# +# nix eval --impure --json --expr ' +# let f = builtins.getFlake (toString ./.); in +# import ./nix/tests/module-peers.nix { +# pkgs = f.inputs.nixpkgs.legacyPackages.x86_64-linux; +# module = f.nixosModules.default; +# }' +# +# Every check throws on failure, so a non-zero exit means the module changed +# behaviour; the returned list names the checks that ran. + +let + inherit (pkgs) lib; + + evalWith = settings: + (import (pkgs.path + "/nixos/lib/eval-config.nix") { + system = "x86_64-linux"; + modules = [ + module + { + system.stateVersion = "24.11"; + services.skyg-linux-tracker = settings; + } + ]; + }).config; + + rendered = settings: (evalWith settings).environment.etc."skyg-linux-tracker.toml".source.value; + service = settings: (evalWith settings).systemd.services.skyg-linux-tracker; + + # Only this module's assertions; a bare evalModules has no root filesystem. + failedAssertions = settings: + map (a: a.message) (builtins.filter + (a: !a.assertion && lib.hasPrefix "services.skyg-linux-tracker" a.message) + (evalWith settings).assertions); + + expect = name: condition: + if condition then name else throw "module-peers eval test failed: ${name}"; + failsWith = settings: needle: + lib.any (m: lib.hasInfix needle m) (failedAssertions settings); + + credentialDir = "/run/credentials/skyg-linux-tracker.service"; + token = name: "/run/agenix/peer-${name}"; + twoPeers = { + enable = true; + peers = { + enable = true; + settings = { tcp_interval_secs = 2; }; + peers = { + beta = { + url = "https://beta:1984"; + tokenFile = token "beta"; + }; + gamma = { + url = "http://gamma:1984"; + tokenFile = token "gamma"; + allowPlainHttp = true; + caFile = "/etc/ssl/private-ca.pem"; + }; + # Declared but switched off: no entry and no credential may be shipped. + off = { + url = "https://off:1984"; + tokenFile = token "off"; + enable = false; + }; + }; + }; + }; + storePath = pkgs.writeText "peer-token" "placeholder"; + + plain = rendered { enable = true; }; + peersCfg = rendered twoPeers; + peersService = service twoPeers; + tlsOnly = { + enable = true; + tls = { + enable = true; + certFile = "/run/agenix/tls-cert"; + keyFile = "/run/agenix/tls-key"; + }; + }; + tlsPeersService = service (twoPeers // { + tls = { + enable = true; + certFile = "/run/agenix/tls-cert"; + keyFile = "/run/agenix/tls-key"; + }; + }); +in +[ + (expect "a peer-less config gains no [peers] section" (!(plain ? peers))) + (expect "a peer-less unit has no peer credentials" + (!((service { enable = true; }).serviceConfig ? LoadCredential))) + (expect "a peer-less unit restarts on config changes" + ((service { enable = true; }).restartTriggers != [ ] + && ((service { enable = true; }).reloadTriggers == [ ]))) + + (expect "peers.enable turns the feature on" (peersCfg.peers.enabled == true)) + (expect "settings are merged into [peers]" (peersCfg.peers.tcp_interval_secs == 2)) + (expect "one [[peers.peer]] per enabled peer, sorted" + ((map (p: p.name) peersCfg.peers.peer) == [ "beta" "gamma" ])) + (expect "a disabled peer is not rendered" + (!(lib.any (p: p.name == "off") peersCfg.peers.peer))) + (expect "token_file points into the credential directory" + (lib.all (p: p.token_file == "${credentialDir}/peer-${p.name}") peersCfg.peers.peer)) + (expect "the token path never appears in the config" + (!(lib.hasInfix (token "beta") (builtins.toJSON peersCfg)))) + (expect "allow_plain_http and ca_file are passed through" ( + (let gamma = lib.findFirst (p: p.name == "gamma") null peersCfg.peers.peer; in + gamma.allow_plain_http && (gamma.ca_file == "/etc/ssl/private-ca.pem")) + && (let beta = lib.findFirst (p: p.name == "beta") null peersCfg.peers.peer; in + (beta.allow_plain_http == false) && !(beta ? ca_file)))) + + (expect "one LoadCredential per enabled peer" + (peersService.serviceConfig.LoadCredential == [ + "peer-beta:/run/agenix/peer-beta" + "peer-gamma:/run/agenix/peer-gamma" + ])) + (expect "reload refreshes credentials" + (peersService.serviceConfig.RefreshOnReload == "credentials")) + (expect "peer changes reload instead of restart" + (peersService.reloadTriggers != [ ] && (peersService.restartTriggers == [ ]))) + + (expect "TLS alone keeps the restart trigger" + ((service tlsOnly).restartTriggers != [ ] && ((service tlsOnly).reloadTriggers == [ ]))) + (expect "TLS credentials are unchanged" + ((service tlsOnly).serviceConfig.LoadCredential == [ + "cert:/run/agenix/tls-cert" + "key:/run/agenix/tls-key" + ])) + (expect "TLS and peers share the credential list" + (tlsPeersService.serviceConfig.LoadCredential == [ + "cert:/run/agenix/tls-cert" + "key:/run/agenix/tls-key" + "peer-beta:/run/agenix/peer-beta" + "peer-gamma:/run/agenix/peer-gamma" + ])) + + # The pre-F1 freeform style stays valid; nix/tests/peers.nix uses it. + (expect "freeform settings.peers still renders" + (((rendered { + enable = true; + settings.peers = { + enabled = true; + peer = [{ name = "alpha"; url = "http://alpha:1984"; token_file = "/run/creds/alpha"; allow_plain_http = true; }]; + }; + }).peers.peer) == [{ name = "alpha"; url = "http://alpha:1984"; token_file = "/run/creds/alpha"; allow_plain_http = true; }])) + + (expect "enable without peers is rejected" + (failsWith { enable = true; peers.enable = true; } "requires at least one peer")) + (expect "peers without enable are rejected" + (failsWith { enable = true; peers.peers.beta = { url = "https://beta:1984"; tokenFile = token "beta"; }; } "requires peers.enable = true")) + (expect "invalid names are rejected" + (failsWith { enable = true; peers = { enable = true; peers."Beta" = { url = "https://beta:1984"; tokenFile = token "beta"; }; }; } "names must match")) + (expect "store paths are rejected as tokenFile" + (failsWith { enable = true; peers = { enable = true; peers.beta = { url = "https://beta:1984"; tokenFile = "${storePath}"; }; }; } "outside the Nix store")) + (expect "relative tokenFile is rejected" + (failsWith { enable = true; peers = { enable = true; peers.beta = { url = "https://beta:1984"; tokenFile = "peer-beta"; }; }; } "absolute path")) + (expect "relative caFile is rejected" + (failsWith { enable = true; peers = { enable = true; peers.beta = { url = "https://beta:1984"; tokenFile = token "beta"; caFile = "ca.pem"; }; }; } "caFile must be an absolute path")) + (expect "mixing first-class and freeform peers is rejected" + (failsWith { + enable = true; + settings.peers.peer = [{ name = "legacy"; url = "https://legacy:1984"; token_file = "/run/creds/legacy"; }]; + peers = { enable = true; peers.beta = { url = "https://beta:1984"; tokenFile = token "beta"; }; }; + } "not settings.peers.peer")) + (expect "a valid peer config passes every assertion" + (failedAssertions twoPeers == [ ])) +]