Headscale 0.29.0: SSH Check, Policy Tests, ACL Compatibility

The client floor moves to 1.80.0

The first thing an operator should note is the minimum supported Tailscale client version, which 0.29.0 raises to 1.80.0. That is a hard floor: nodes running an older client are not supported by this release. Before rolling out 0.29.0, an operator should check the client versions across the fleet and plan to upgrade any node below the floor, because a node that cannot meet the floor is not just degraded, it is unsupported. This is the kind of change that is easy to miss until a node stops behaving as expected.

The floor matters most at the edges of a fleet, where a few forgotten nodes run an older client. A systematic inventory of client versions before the upgrade is the cheap way to avoid finding out, node by node, that some of them are below the supported line.

SSH check actions and the approval flow

The SSH check action is a new way to gate SSH access in a mesh. Instead of an SSH rule that is simply allow or deny, a check action means the connection is held pending an approval: the user authenticates via OIDC or the operator approves via CLI before access is granted. The headscale auth command group is what supports that flow, with approve and reject for pending requests and register for node registration, replacing the deprecated nodes register command.

There are two constraints an operator must design around. First, OIDC approval requires the authenticated user to own the source node, so a user cannot approve SSH from a node they do not own. Second, tagged source nodes cannot use SSH check mode at all. That means check mode is for user-owned source nodes, which is the right fit for an interactive approval flow but not for server-to-server SSH from tagged infrastructure. Plan which of your SSH flows are interactive and which are automated, because only the former can use check mode.

Policy tests: rejecting a bad policy before it lands

The beta policy-tests block is the most operationally significant addition, because it moves policy validation from after a problem to before a bad policy is applied. A tests block asserts reachability between named sources and destinations, and it covers the whole policy, both the acls and the grants rules. The tests run three ways: on a user-initiated policy write, on a SIGHUP reload, and on headscale policy check. When a test fails, the write is rejected before it is applied, and the error message matches what Tailscale SaaS would return for the same policy.

The beta caveat is stated plainly in the release notes: behavioral coverage against Tailscale SaaS is still broadening, so an operator should treat the tests as a strong guardrail, not a complete equivalence guarantee. At boot, a stored policy whose tests no longer pass, for example because a referenced user was deleted while the server was offline, logs a warning and the server keeps running. The fix is to correct the policy and reload. That boot behavior is worth understanding, because it means a bad stored policy does not take the server down, but it does mean the policy may not be doing what you intend until you fix it.

ACL compatibility from systematic testing

The third addition is less visible but it addresses a long-standing gap: Headscale generating a packet filter that differs from what Tailscale SaaS generates for the same policy. The release notes describe systematically generating test cases using Tailscale clients and the official SaaS to understand how the filter should be generated, then fixing the differences that were found. The result is that the implementation was very close already, and the remaining differences were corrected.

For an operator, the practical benefit is that a policy that works on SaaS is now much more likely to work the same way on Headscale. The class of problem where a mesh behaves differently from SaaS for an identical policy is smaller. This does not make Headscale identical to SaaS, and the policy-tests feature is the explicit mechanism for catching the cases that still differ, but the baseline compatibility is better than it was before 0.29.0.

What to verify on upgrade

The upgrade checklist follows the three additions. First, confirm every node meets the 1.80.0 client floor before you roll out. Second, if you use SSH, decide which flows can use check mode, set up the headscale auth approval flow for the interactive ones, and confirm the tagged-node constraint does not block a flow you need. Third, if you adopt policy tests, write the tests block against your current policy, run headscale policy check to confirm it passes, and observe the reject-on-fail behavior with a deliberately bad policy before you rely on it in production. The policy-tests feature is beta, so adopt it deliberately and keep the boot-warning behavior in mind.

Limitations

• A release note is not a deployment audit. It does not inspect your operating system, network policy, credentials, storage, backups, or administrative process.
• Version numbers and documentation change. Pin the exact artifacts you test, record the date, and re-check upstream material before a production change.
• A feature that exists in a package or command does not automatically fit your threat model. Authentication, authorization, logging, patching, recovery, and abuse controls remain operator responsibilities.
• This article contains no benchmark, uptime promise, adoption statistic, cost saving, or client result. Measure those claims in your environment; the release record can only describe what shipped.

Related infrastructure context

For the physical layer around a systems deployment, TismTek provides fiber and network infrastructure work near Aurora. The team also documents on-premises compute and private AI systems. For a site discussion, call (720) 694-1976. See the Headscale registration and policy for recovery planning and the 3-2-1 backup strategy for the broader on-premises context.