-
API: The Node message in the gRPC/REST API has been simplified - the ForcedTags, InvalidTags, and ValidTags fields have been removed and replaced with a single Tags field that contains the node's applied tags #2993
- API clients should use the
Tags field instead of ValidTags
- The
headscale nodes list CLI command now always shows a Tags column and the --tags flag has been removed
-
PreAuthKey CLI: Commands now use ID-based operations instead of user+key combinations #2992
headscale preauthkeys create no longer requires --user flag (optional for tracking creation)headscale preauthkeys list lists all keys (no longer filtered by user)headscale preauthkeys expire --id <ID> replaces --user <USER> <KEY>headscale preauthkeys delete --id <ID> replaces --user <USER> <KEY>
Before:
headscale preauthkeys create --user 1 --reusable --tags tag:server
headscale preauthkeys list --user 1
headscale preauthkeys expire --user 1 <KEY>
headscale preauthkeys delete --user 1 <KEY>
After:
headscale preauthkeys create --reusable --tags tag:server
headscale preauthkeys list
headscale preauthkeys expire --id 123
headscale preauthkeys delete --id 123
-
Tags: The gRPC SetTags endpoint now allows converting user-owned nodes to tagged nodes by setting tags. #2885
-
Tags: Tags are now resolved from the node's stored Tags field only #2931
--advertise-tags is processed during registration, not on every policy evaluation- PreAuthKey tagged devices ignore
--advertise-tags from clients
- User-owned nodes can use
--advertise-tags if authorized by tagOwners policy
- Tags can be managed via CLI (
headscale nodes tag) or the SetTags API after registration
-
Database migration support removed for pre-0.25.0 databases #2883
- If you are running a version older than 0.25.0, you must upgrade to 0.25.1 first, then upgrade to this release
- See the upgrade path documentation for detailed guidance
- In version 0.29, all migrations before 0.28.0 will also be removed
-
Remove ability to move nodes between users #2922
- The
headscale nodes move CLI command has been removed
- The
MoveNode API endpoint has been removed
- Nodes are permanently associated with their user or tag at registration time
-
Add oidc.email_verified_required config option to control email verification requirement #2860
- When
true (default), only verified emails can authenticate via OIDC in conjunction with oidc.allowed_domains or
oidc.allowed_users. Previous versions allowed to authenticate with an unverified email but did not store the email
address in the user profile. This is now rejected during authentication with an unverified email error.
- When
false, unverified emails are allowed for OIDC authentication and the email address is stored in the user
profile regardless of its verification state.
-
SSH Policy: Wildcard (*) is no longer supported as an SSH destination #3009
- Use
autogroup:member for user-owned devices
- Use
autogroup:tagged for tagged devices
- Use specific tags (e.g.,
tag:server) for targeted access
Before:
{ "action": "accept", "src": ["group:admins"], "dst": ["*"], "users": ["root"] }
After:
{ "action": "accept", "src": ["group:admins"], "dst": ["autogroup:member", "autogroup:tagged"], "users": ["root"] }
-
SSH Policy: SSH source/destination validation now enforces Tailscale's security model #3010
Per Tailscale SSH documentation, the following rules are now enforced:
- Tags cannot SSH to user-owned devices: SSH rules with
tag:* or autogroup:tagged as source cannot have username destinations (e.g., alice@) or autogroup:member/autogroup:self as destination
- Username destinations require same-user source: If destination is a specific username (e.g.,
alice@), the source must be that exact same user only. Use autogroup:self for same-user SSH access instead
Invalid policies now rejected at load time:
// INVALID: tag source to user destination
{"src": ["tag:server"], "dst": ["alice@"], ...}
// INVALID: autogroup:tagged to autogroup:member
{"src": ["autogroup:tagged"], "dst": ["autogroup:member"], ...}
// INVALID: group to specific user (use autogroup:self instead)
{"src": ["group:admins"], "dst": ["alice@"], ...}
Valid patterns:
// Users/groups can SSH to their own devices via autogroup:self
{"src": ["group:admins"], "dst": ["autogroup:self"], ...}
// Users/groups can SSH to tagged devices
{"src": ["group:admins"], "dst": ["autogroup:tagged"], ...}
// Tagged devices can SSH to other tagged devices
{"src": ["autogroup:tagged"], "dst": ["autogroup:tagged"], ...}
// Same user can SSH to their own devices
{"src": ["alice@"], "dst": ["alice@"], ...}