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.
Adapted: no file: secret warning; groups as after activation; a new primary
group skips; the policy the unit's env selects; docs say which check covers
the policy; VM case for the unit's env.

(cherry picked from commit b6ba6e42ee)

Fixes #2898
Updates #1926
This commit is contained in:
Kristoffer Dalby committed 2026-11-11 12:19:29 +01:00
1 parent 3dcc107efa
commit 4185b2481c
5 files changed
+420 -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.
@@ -402,11 +413,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);
inherit nixos-options;
}
);
+151 -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,116 @@ let
settingsFormat = pkgs.formats.yaml { };
cliConfigFile = settingsFormat.generate "headscale.yaml" cliConfig;
# headscale reads a non-empty variable of the unit over the setting.
effective =
name: setting:
let
v = config.systemd.services.headscale.environment.${name} or null;
in
if v == null || v == "" then setting else v;
policyMode = effective "HEADSCALE_POLICY_MODE" cfg.settings.policy.mode;
policyPath = effective "HEADSCALE_POLICY_PATH" cfg.settings.policy.path;
# Interpolated as the config and the unit are, so a Nix path is the same store path.
policyFile = if policyMode == "file" && policyPath != null then "${policyPath}" 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 script, for shellcheck and runtimeInputs.
preSwitchCheck =
let
user = lib.escapeShellArg cfg.user;
group = lib.escapeShellArg cfg.group;
# systemd gives the unit Group= and the account's /etc/group memberships.
# Activation rewrites a declared account's memberships in the groups
# NixOS declares (members holds extraGroups), so those come from the new
# configuration. It keeps the rest: an undeclared account's, and with
# mutableUsers a hand-made group.
managed = config.users.users ? ${cfg.user};
groups = [
cfg.group
]
++ lib.optionals managed (
map (g: g.name) (lib.filter (g: lib.elem cfg.user g.members) (lib.attrValues config.users.groups))
)
++ lib.filter (g: g != "") (
lib.concatMap (g: lib.splitString " " (toString g)) (
lib.toList (config.systemd.services.headscale.serviceConfig.SupplementaryGroups or [ ])
)
);
keepCurrent = !managed || config.users.mutableUsers;
declared = lib.optionals managed (map (g: g.name) (lib.attrValues config.users.groups));
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.getent
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 and groups 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
if ! getent group ${group} >/dev/null; then
echo "headscale: group" ${group} "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
# A group this switch creates does not exist yet; setpriv would fail on it.
want=(${lib.escapeShellArgs groups})
${lib.optionalString keepCurrent ''
# Not the account's primary group, which the unit does not get, nor a
# group NixOS declares now, or declared before and activation removes.
skip=" $(id -gn ${user} 2>/dev/null || true) "${lib.escapeShellArg (toString declared)}" ${lib.optionalString managed "$(cat /var/lib/nixos/declarative-groups 2>/dev/null || true)"} "
for g in $(id -Gn ${user}); do
[[ $skip == *" $g "* ]] || want+=("$g")
done
''}
groups=()
for g in "''${want[@]}"; do
if getent group "$g" >/dev/null; then groups+=("$g"); fi
done
grouplist=$(IFS=,; echo "''${groups[*]}")
# As the unit's user and groups, with the unit's environment rather than the caller's.
hs() {
setpriv --reuid=${user} --regid=${group} --groups="$grouplist" -- \
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 +156,40 @@ 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`. Keys are read, never
created.
It runs outside the unit, and only when headscale's unit changes.
It never reads a `file:` secret, so credentials referenced with
`file:` pass. Turning off only {option}`services.headscale.check.policy`
does not skip the policy here. 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: it checks the policy and runs its `tests` and `sshTests`
against one node for each user and tag the policy names. 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.
{option}`services.headscale.check.config` checks the policy before a
switch too; turn off both to skip every policy check.
'';
};
user = lib.mkOption {
default = "headscale";
type = lib.types.str;
@@ -770,6 +913,12 @@ in
] "Use `oidc.client_secret = \"file:<path>\"` instead.")
];
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 = {
+253
View File
@@ -0,0 +1,253 @@
# A policy headscale rejects must fail the build, and a config or policy it
# rejects must fail a switch before headscale restarts.
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.
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";
# Readable only through the group headscale.
oldGroupPolicy = "/var/lib/hsold/policy.json";
# Readable only through hshand, a group made by hand.
handGroupPolicy = "/var/lib/hshand/policy.json";
# Readable only through the group hsread.
groupPolicy = "/var/lib/hsread/policy.json";
badServerUrl = lib.mkForce "ftp://headscale";
in
{
name = "headscale-checks";
meta.maintainers = with lib.maintainers; [ kradalby ];
nodes.headscale = {
imports = [
self.nixosModules.testkit
# Specialisations that set more than services.headscale.
{
specialisation = lib.mapAttrs (_: c: { configuration = c; }) {
unitEnv.systemd.services.headscale.environment.HEADSCALE_SERVER_URL = "ftp://headscale";
newGroup = {
services.headscale.group = "hs3";
users.groups.hs3 = { };
};
# hsnew is created by this switch, so the check leaves it out.
supplementaryGroup = {
services.headscale.settings.policy.path = lib.mkForce groupPolicy;
users.groups.hsnew = { };
systemd.services.headscale.serviceConfig.SupplementaryGroups = [
"hsread"
"hsnew"
];
};
extraGroup = {
services.headscale.settings.policy.path = lib.mkForce groupPolicy;
users.users.headscale.extraGroups = [ "hsread" ];
};
memberGroup = {
services.headscale.settings.policy.path = lib.mkForce groupPolicy;
users.groups.hsread.members = [ "headscale" ];
};
};
}
];
services.headscale.settings.policy = {
mode = "file";
path = valid;
};
users.groups.hsread = { };
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;
# After activation the user is no longer in its old primary group headscale.
newPrimaryGroup = {
group = "hsread";
settings.policy.path = lib.mkForce oldGroupPolicy;
};
# Activation keeps a membership of a group NixOS does not declare.
handGroup.settings.policy.path = lib.mkForce handGroupPolicy;
credential.settings.dns = {
certificates.enabled = true;
challenge.provider = {
name = "rfc2136";
server = "127.0.0.1:53";
key_name = "headscale.";
key_alg = "hmac-sha256.";
key = "file:\${CREDENTIALS_DIRECTORY}/tsig";
};
};
};
};
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")
assert_rejected("unitEnv", "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}")
# The caller's environment does not reach the check.
headscale.succeed("HEADSCALE_SERVER_URL=ftp://headscale " + stc("mutable", "check"))
with subtest("the check has the unit's groups"):
headscale.succeed("install -d -m 750 -g hsread ${builtins.dirOf groupPolicy}")
headscale.succeed("install -m 640 -g hsread ${valid} ${groupPolicy}")
headscale.succeed(stc("supplementaryGroup", "check"))
headscale.succeed(stc("extraGroup", "check"))
headscale.succeed(stc("memberGroup", "check"))
headscale.succeed("groupadd hshand && usermod -aG hshand headscale")
headscale.succeed("install -d -m 750 -g hshand ${builtins.dirOf handGroupPolicy}")
headscale.succeed("install -m 640 -g hshand ${valid} ${handGroupPolicy}")
headscale.succeed(stc("handGroup", "check"))
headscale.succeed("install -d -m 750 -g headscale ${builtins.dirOf oldGroupPolicy}")
headscale.succeed("install -m 640 -g headscale ${valid} ${oldGroupPolicy}")
assert_rejected("newPrimaryGroup", "permission denied")
with subtest("a file: secret is skipped, not read"):
out = headscale.succeed(stc("credential", "check"))
assert "secret, not read" in out, out
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
out = headscale.succeed(stc("newGroup", "check"))
assert 'group hs3 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"
'';
}