nix: check the policy at build time and the config before a switch

Store-path policy: check policy -f in system.checks.
Pre-switch: check all as the headscale user. Offline, no DB copy.

Fixes #2898
This commit is contained in:
Kristoffer Dalby committed 2026-11-07 21:25:44 +00:00
1 parent 66a50a1241
commit b6ba6e42ee
5 files changed
+306 -7

No files matched your search

+1 -1
View File
@@ -49,4 +49,4 @@ jobs:
if: steps.changed-files.outputs.nix == 'true' || steps.changed-files.outputs.go == 'true'
run: |
echo "Running NixOS module integration test..."
nix build .#checks.x86_64-linux.headscale -L --fallback
nix build .#checks.x86_64-linux.headscale .#checks.x86_64-linux.headscale-checks -L --fallback
+15 -3
View File
@@ -25,8 +25,19 @@
{
# NixOS module
nixosModules = rec {
# A path, so importing it twice (directly and via testkit) dedupes.
headscale = ./nix/module.nix;
# Defaults the package to this flake's: the pre-switch checks need
# `headscale check`. Priority 1001 sits just below mkDefault, so a
# user's mkDefault wins instead of conflicting. The overlay, not
# self.packages, so every system nixpkgs supports evaluates.
headscale =
{ lib, pkgs, ... }:
{
# Dedupes importing it twice, directly and via testkit.
key = "${toString ./flake.nix}#nixosModules.headscale";
_file = "${toString ./flake.nix}#nixosModules.headscale";
imports = [ ./nix/module.nix ];
services.headscale.package = lib.mkOverride 1001 (self.overlays.default pkgs pkgs).headscale;
};
default = headscale;
# Control node for NixOS VM tests of Tailscale clients, and a peer
# that joins it; nix/README.md.
@@ -308,11 +319,12 @@
);
# Gated to Linux: parts of the tree are Linux-specific, and the VM
# test needs KVM.
# tests need KVM.
checks = pkgs.lib.optionalAttrs pkgs.stdenv.hostPlatform.isLinux (
goChecks
// {
headscale = pkgs.testers.runNixOSTest (import ./nix/tests/headscale.nix self);
headscale-checks = pkgs.testers.runNixOSTest (import ./nix/tests/checks.nix self);
}
);
}
+112 -2
View File
@@ -11,8 +11,7 @@ let
runDir = "/run/headscale";
cliConfig = {
# Turn off update checks since the origin of our package
# is nixpkgs and not Github.
# Nix pins the package, so an update notice cannot be acted on.
disable_check_updates = true;
unix_socket = "${runDir}/headscale.sock";
@@ -21,6 +20,72 @@ let
settingsFormat = pkgs.formats.yaml { };
cliConfigFile = settingsFormat.generate "headscale.yaml" cliConfig;
# Interpolated, so a Nix path lands at the same store path the config names.
policyFile =
if cfg.settings.policy.mode == "file" && cfg.settings.policy.path != null then
"${cfg.settings.policy.path}"
else
null;
policyFileCheck = cfg.check.policy && policyFile != null;
# The build can read a store path, and must be able to run the binary.
buildTimePolicy =
policyFileCheck
&& lib.hasPrefix "${builtins.storeDir}/" policyFile
&& pkgs.stdenv.buildPlatform.canExecute pkgs.stdenv.hostPlatform;
preSwitchPolicy = policyFileCheck && !buildTimePolicy;
policyCheck = pkgs.runCommand "headscale-policy-check" { } ''
${lib.getExe cfg.package} check policy -f ${lib.escapeShellArg policyFile}
touch $out
'';
# Its own process, so errexit holds: nixpkgs 25.11 and older run each
# pre-switch check inside `if ! (…)`, where bash ignores errexit.
preSwitchCheck =
let
user = lib.escapeShellArg cfg.user;
group = lib.escapeShellArg cfg.group;
unitEnv = lib.mapAttrsToList (n: v: "${n}=${toString v}") (
lib.filterAttrs (_: v: v != null) config.systemd.services.headscale.environment
);
in
pkgs.writeShellApplication {
name = "headscale-pre-switch-check";
runtimeInputs = [
pkgs.coreutils
pkgs.util-linux
];
text = ''
# An unchanged unit is not restarted, so there is nothing to protect.
unit=etc/systemd/system/headscale.service
if [ "$(readlink -f "/run/current-system/$unit")" = "$(readlink -f "$1/$unit")" ]; then
echo "headscale: unit unchanged, skipping checks"
exit 0
fi
# Activation creates users after this check runs.
if ! id -u ${user} >/dev/null 2>&1; then
echo "headscale: user" ${user} "does not exist yet, skipping checks"
exit 0
fi
trap '[ "$?" = 0 ] || echo "headscale: to skip, set services.headscale.check.config and check.policy to false, or run once with NIXOS_NO_CHECK=1"' EXIT
# As the unit's user, with the unit's environment rather than the caller's.
hs() {
setpriv --reuid=${user} --regid=${group} --init-groups -- \
env -i ${lib.escapeShellArgs unitEnv} ${lib.getExe cfg.package} "$@"
}
${lib.optionalString cfg.check.config ''
echo "headscale: checking the new configuration"
hs check all -f ${cfg.configFile}
''}
${lib.optionalString preSwitchPolicy ''
echo "headscale: checking the new policy"
hs check policy -f ${lib.escapeShellArg policyFile}
''}
'';
};
assertRemovedOption = option: message: {
assertion = !lib.hasAttrByPath option cfg;
message =
@@ -47,6 +112,36 @@ in
'';
};
check.config = lib.mkOption {
type = lib.types.bool;
default = true;
description = ''
Before a switch restarts headscale, run the new package's
`headscale check all` on the new configuration and abort the switch
if it fails. It checks the configuration and every file it names
(policy, DERP maps, extra records, TLS pair, existing noise and DERP
keys) as {option}`services.headscale.user`, offline: no database,
network or server. Keys are read, never created.
It runs outside the unit, and only when headscale's unit changes.
Settings that read {env}`CREDENTIALS_DIRECTORY` fail it. Skip all
checks once with `NIXOS_NO_CHECK=1`.
'';
};
check.policy = lib.mkOption {
type = lib.types.bool;
default = true;
description = ''
In file policy mode, run `headscale check policy -f` on the new
policy, including its `tests` and `sshTests` against stand-in users
and nodes. A policy in the Nix store is checked while building the
system (native builds only), so a bad policy fails
`nixos-rebuild build`. Any other policy is checked before a switch
restarts headscale.
'';
};
user = lib.mkOption {
default = "headscale";
type = lib.types.str;
@@ -779,6 +874,21 @@ in
] "Use `node.ephemeral.inactivity_timeout` instead.")
];
warnings =
lib.optional
(cfg.check.config && lib.hasInfix "CREDENTIALS_DIRECTORY" (builtins.toJSON cfg.settings))
''
services.headscale.settings read $CREDENTIALS_DIRECTORY, which is set
only inside the unit, so the check before a switch fails. Set
services.headscale.check.config to false.
'';
system.checks = lib.optional buildTimePolicy policyCheck;
system.preSwitchChecks.headscale = lib.mkIf (
cfg.check.config || preSwitchPolicy
) ''${lib.getExe preSwitchCheck} "$@"'';
services.headscale.settings = lib.mkMerge [
cliConfig
{
-1
View File
@@ -35,7 +35,6 @@ in
services.headscale = {
enable = true;
package = lib.mkDefault self.packages.${pkgs.stdenv.hostPlatform.system}.headscale;
address = "[::]";
port = 80;
settings = {
+178
View File
@@ -0,0 +1,178 @@
# A policy headscale rejects must fail the build, and a config or policy it
# rejects must fail a switch before headscale restarts. Every check is offline.
self:
{ lib, pkgs, ... }:
let
writePolicy = name: policy: pkgs.writeText name (builtins.toJSON policy);
acceptAll = [
{
action = "accept";
src = [ "*" ];
dst = [ "*:*" ];
}
];
valid = writePolicy "valid.json" { acls = acceptAll; };
# group:missing is never defined.
undefinedGroup = writePolicy "undefined-group.json" {
acls = [
{
action = "accept";
src = [ "group:missing" ];
dst = [ "*:*" ];
}
];
};
# Stand-in users and nodes decide these tests offline.
testsPass = writePolicy "tests-pass.json" {
acls = acceptAll;
tests = [
{
src = "test@";
accept = [ "test@:22" ];
}
];
};
testsFail = writePolicy "tests-fail.json" {
acls = acceptAll;
tests = [
{
src = "test@";
deny = [ "test@:22" ];
}
];
};
# The build-time check a system with this store-path policy must pass.
policyBuild =
policy:
lib.findFirst (d: d.name == "headscale-policy-check") (throw "no headscale-policy-check")
(pkgs.nixos {
imports = [ self.nixosModules.headscale ];
services.headscale = {
enable = true;
settings.policy = {
mode = "file";
path = policy;
};
};
}).config.system.checks;
buildFailures = {
undefinedGroup = pkgs.testers.testBuildFailure (policyBuild undefinedGroup);
testsFail = pkgs.testers.testBuildFailure (policyBuild testsFail);
};
# Outside the store, so only the switch can check it.
mutablePolicy = "/var/lib/headscale/policy.json";
badServerUrl = lib.mkForce "ftp://headscale";
in
{
name = "headscale-checks";
meta.maintainers = with lib.maintainers; [ kradalby ];
nodes.headscale = {
imports = [ self.nixosModules.testkit ];
services.headscale.settings.policy = {
mode = "file";
path = valid;
};
specialisation = lib.mapAttrs (_: c: { configuration.services.headscale = c; }) {
badConfig.settings.server_url = badServerUrl;
mutable.settings.policy.path = lib.mkForce mutablePolicy;
policyOnly = {
settings.policy.path = lib.mkForce mutablePolicy;
check.config = false;
};
unchecked = {
settings.server_url = badServerUrl;
check = {
config = false;
policy = false;
};
};
newUser = {
user = "hs2";
group = "hs2";
};
testsPass.settings.policy.path = lib.mkForce testsPass;
};
};
testScript =
{ nodes, ... }:
let
toplevel = nodes.headscale.system.build.toplevel;
jq = lib.getExe pkgs.jq;
in
''
from datetime import timedelta
def stc(spec, action):
return f"${toplevel}/specialisation/{spec}/bin/switch-to-configuration {action} 2>&1"
def main_pid():
return headscale.succeed("systemctl show -P MainPID headscale.service").strip()
def served_policy():
return headscale.succeed("headscale policy get | ${jq} -S .")
def put_policy(src, mode="644"):
headscale.succeed(f"install -m {mode} {src} ${mutablePolicy}")
def assert_rejected(spec, why):
out = headscale.fail(stc(spec, "test"))
assert "Pre-switch check 'headscale' failed" in out, out
assert why in out, out
assert "NIXOS_NO_CHECK=1" in out, "no skip hint:\n" + out
return out
with subtest("a bad store-path policy fails the build"):
for path, why in [
("${buildFailures.undefinedGroup}", 'group not found: "group:missing"'),
("${buildFailures.testsFail}", "test(s) failed"),
]:
build_log = open(f"{path}/testBuildFailure.log").read()
assert why in build_log, build_log
headscale.wait_for_unit("headscale.service")
headscale.wait_until_succeeds("headscale health", timeout=timedelta(seconds=60))
with subtest("rejected switches leave the running headscale alone"):
pid = main_pid()
before = served_policy()
assert_rejected("badConfig", "server_url is missing a scheme")
put_policy("${undefinedGroup}")
assert_rejected("mutable", 'group not found: "group:missing"')
put_policy("${testsFail}")
assert_rejected("mutable", "test(s) failed")
out = assert_rejected("policyOnly", "test(s) failed")
assert "checking the new configuration" not in out, out
# Checked as the headscale user, who cannot read this file.
put_policy("${valid}", "600")
assert_rejected("mutable", "permission denied")
assert main_pid() == pid, "headscale was restarted"
assert served_policy() == before, "old policy no longer served"
headscale.succeed("headscale health")
with subtest("a passing switch check"):
put_policy("${valid}")
headscale.succeed(stc("mutable", "check"))
with subtest("skips"):
out = headscale.succeed("${toplevel}/bin/switch-to-configuration check 2>&1")
assert "unit unchanged" in out, out
out = headscale.succeed(stc("newUser", "check"))
assert "does not exist yet" in out, out
with subtest("escape hatches"):
headscale.succeed(stc("unchecked", "check"))
headscale.succeed("NIXOS_NO_CHECK=1 " + stc("badConfig", "check"))
with subtest("a valid switch goes through and applies the policy"):
pid = main_pid()
headscale.succeed(stc("testsPass", "test"))
headscale.wait_until_succeeds("headscale health", timeout=timedelta(seconds=60))
assert main_pid() != pid, "headscale was not restarted"
want = headscale.succeed("${jq} -S . ${testsPass}")
assert served_policy() == want, "new policy not served"
'';
}