NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Go modules, #38 by repository stars
Latest stable
v0.29.7
Last release today
20 Nov 2026
Ships fairly regularly
a new release about every 2 weeks
Nearly every release is documented
notes for 57 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
6 years old
589 releases · first in 2020
Drag across the ruler to compare, or tap a release to open it.
Be sure to check the changelog above for version-specific upgrade instructions and breaking changes.
Minimum supported Tailscale client version: v1.64.0
Please follow the steps outlined in the upgrade guide to update your existing Headscale installation.
It's best to update from one stable version to the next (e.g., 0.24.0 → 0.25.1 → 0.26.1) in case you are multiple releases behind. You should always pick the latest available patch release.
Be sure to check the changelog above for version-specific upgrade instructions and breaking changes.
Always backup your database before upgrading. Here's how to backup a SQLite database:
# Stop headscale
systemctl stop headscale
# Backup sqlite database
cp /var/lib/headscale/db.sqlite /var/lib/headscale/db.sqlite.backup
# Backup sqlite WAL/SHM files (if they exist)
cp /var/lib/headscale/db.sqlite-wal /var/lib/headscale/db.sqlite-wal.backup
cp /var/lib/headscale/db.sqlite-shm /var/lib/headscale/db.sqlite-shm.backup
# Start headscale (migration will run automatically)
systemctl start headscale
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Be sure to check the changelog above for version-specific upgrade instructions and breaking changes.
Minimum supported Tailscale client version: v1.64.0
This release includes a significant database migration that addresses
longstanding issues with the database schema and data integrity that has
accumulated over the years. The migration introduces a schema.sql file as the
source of truth for the expected database schema to ensure new migrations that
will cause divergence does not occur again.
These issues arose from a combination of factors discovered over time: SQLite foreign keys not being enforced for many early versions, all migrations being run in one large function until version 0.23.0, and inconsistent use of GORM's AutoMigrate feature. Moving forward, all new migrations will be explicit SQL operations rather than relying on GORM AutoMigrate, and foreign keys will be enforced throughout the migration process.
We are only improving SQLite databases with this change - PostgreSQL databases are not affected.
Please read the PR description for more technical details about the issues and solutions.
SQLite Database Backup Example:
# Stop headscale
systemctl stop headscale
# Backup sqlite database
cp /var/lib/headscale/db.sqlite /var/lib/headscale/db.sqlite.backup
# Backup sqlite WAL/SHM files (if they exist)
cp /var/lib/headscale/db.sqlite-wal /var/lib/headscale/db.sqlite-wal.backup
cp /var/lib/headscale/db.sqlite-shm /var/lib/headscale/db.sqlite-shm.backup
# Start headscale (migration will run automatically)
systemctl start headscale
The default DERPMap update frequency has been changed from 24 hours to 3 hours.
If you set the derp.update_frequency configuration option, it is recommended
to change it to 3h to ensure that the headscale instance gets the latest
DERPMap updates when upstream is changed.
This release adds support for the three missing autogroups: self
(experimental), member, and tagged. Please refer to the
documentation for a detailed
explanation.
autogroup:self is marked as experimental and should be used with caution, but
we need help testing it. Experimental here means two things; first, generating
the packet filter from policies that use autogroup:self is very expensive, and
it might perform, or straight up not work on Headscale installations with a
large number of nodes. Second, the implementation might have bugs or edge cases
we are not aware of, meaning that nodes or users might gain more access than
expected. Please report bugs.
Under the hood, we have added a new datastructure to store nodes in memory. This
datastructure is called NodeStore and aims to reduce the reading and writing
of nodes to the database layer. We have not benchmarked it, but expect it to
improve performance for read heavy workloads. We think of it as, "worst case" we
have moved the bottle neck somewhere else, and "best case" we should see a good
improvement in compute resource usage at the expense of memory usage. We are
quite excited for this change and think it will make it easier for us to improve
the code base over time and make it more correct and efficient.
invalid-XXXXXX format
my-laptop → accepted as-isMy-Laptop → my-laptop (lowercased)my_laptop → invalid-a1b2c3 (underscore not allowed)test@host → invalid-d4e5f6 (@ not allowed)laptop-🚀 → invalid-j1k2l3 (emoji not allowed)autogroup:member, autogroup:tagged
#2572noise config
#2658/robots.txt endpoint to avoid crawlers
#2643autogroup:self
#2789Please follow the steps outlined in the upgrade guide to update your existing Headscale installation.
It's best to update from one stable version to the next (e.g., 0.24.0 → 0.25.1 → 0.26.1) in case you are multiple releases behind. You should always pick the latest available patch release.
Be sure to check the changelog above for version-specific upgrade instructions and breaking changes.
Always backup your database before upgrading. Here's how to backup a SQLite database:
# Stop headscale
systemctl stop headscale
# Backup sqlite database
cp /var/lib/headscale/db.sqlite /var/lib/headscale/db.sqlite.backup
# Backup sqlite WAL/SHM files (if they exist)
cp /var/lib/headscale/db.sqlite-wal /var/lib/headscale/db.sqlite-wal.backup
cp /var/lib/headscale/db.sqlite-shm /var/lib/headscale/db.sqlite-shm.backup
# Start headscale (migration will run automatically)
systemctl start headscale
Nothing published for this version
Minimum supported Tailscale client version: v1.64.0
Minimum supported Tailscale client version: v1.64.0
This release includes a significant database migration that addresses
longstanding issues with the database schema and data integrity that has
accumulated over the years. The migration introduces a schema.sql file as the
source of truth for the expected database schema to ensure new migrations that
will cause divergence does not occur again.
These issues arose from a combination of factors discovered over time: SQLite foreign keys not being enforced for many early versions, all migrations being run in one large function until version 0.23.0, and inconsistent use of GORM's AutoMigrate feature. Moving forward, all new migrations will be explicit SQL operations rather than relying on GORM AutoMigrate, and foreign keys will be enforced throughout the migration process.
We are only improving SQLite databases with this change - PostgreSQL databases are not affected.
Please read the PR description for more technical details about the issues and solutions.
SQLite Database Backup Example:
# Stop headscale
systemctl stop headscale
# Backup sqlite database
cp /var/lib/headscale/db.sqlite /var/lib/headscale/db.sqlite.backup
# Backup sqlite WAL/SHM files (if they exist)
cp /var/lib/headscale/db.sqlite-wal /var/lib/headscale/db.sqlite-wal.backup
cp /var/lib/headscale/db.sqlite-shm /var/lib/headscale/db.sqlite-shm.backup
# Start headscale (migration will run automatically)
systemctl start headscale
The default DERPMap update frequency has been changed from 24 hours to 3 hours.
If you set the derp.update_frequency configuration option, it is recommended
to change it to 3h to ensure that the headscale instance gets the latest
DERPMap updates when upstream is changed.
This release adds support for the three missing autogroups: self
(experimental), member, and tagged. Please refer to the
documentation for a detailed
explanation.
autogroup:self is marked as experimental and should be used with caution, but
we need help testing it. Experimental here means two things; first, generating
the packet filter from policies that use autogroup:self is very expensive, and
it might perform, or straight up not work on Headscale installations with a
large number of nodes. Second, the implementation might have bugs or edge cases
we are not aware of, meaning that nodes or users might gain more access than
expected. Please report bugs.
Under the hood, we have added a new datastructure to store nodes in memory. This
datastructure is called NodeStore and aims to reduce the reading and writing
of nodes to the database layer. We have not benchmarked it, but expect it to
improve performance for read heavy workloads. We think of it as, "worst case" we
have moved the bottle neck somewhere else, and "best case" we should see a good
improvement in compute resource usage at the expense of memory usage. We are
quite excited for this change and think it will make it easier for us to improve
the code base over time and make it more correct and efficient.
invalid-XXXXXX format
my-laptop → accepted as-isMy-Laptop → my-laptop (lowercased)my_laptop → invalid-a1b2c3 (underscore not allowed)test@host → invalid-d4e5f6 (@ not allowed)laptop-🚀 → invalid-j1k2l3 (emoji not allowed)autogroup:member, autogroup:tagged
#2572noise config
#2658/robots.txt endpoint to avoid crawlers
#2643autogroup:self
#2789Nothing published for this version
bad783321e8ea0c77bd00933bfd5d18ec8e05bca Fix /machine/map endpoint vulnerability
Minimum supported Tailscale client version: v1.64.0
This release includes a significant database migration that addresses
longstanding issues with the database schema and data integrity that has
accumulated over the years. The migration introduces a schema.sql file as the
source of truth for the expected database schema to ensure new migrations that
will cause divergence does not occur again.
These issues arose from a combination of factors discovered over time: SQLite foreign keys not being enforced for many early versions, all migrations being run in one large function until version 0.23.0, and inconsistent use of GORM's AutoMigrate feature. Moving forward, all new migrations will be explicit SQL operations rather than relying on GORM AutoMigrate, and foreign keys will be enforced throughout the migration process.
We are only improving SQLite databases with this change - PostgreSQL databases are not affected.
Please read the PR description for more technical details about the issues and solutions.
SQLite Database Backup Example:
# Stop headscale
systemctl stop headscale
# Backup sqlite database
cp /var/lib/headscale/db.sqlite /var/lib/headscale/db.sqlite.backup
# Backup sqlite WAL/SHM files (if they exist)
cp /var/lib/headscale/db.sqlite-wal /var/lib/headscale/db.sqlite-wal.backup
cp /var/lib/headscale/db.sqlite-shm /var/lib/headscale/db.sqlite-shm.backup
# Start headscale (migration will run automatically)
systemctl start headscale
The default DERPMap update frequency has been changed from 24 hours to 3 hours.
If you set the derp.update_frequency configuration option, it is recommended
to change it to 3h to ensure that the headscale instance gets the latest
DERPMap updates when upstream is changed.
This release adds support for the three missing autogroups: self
(experimental), member, and tagged. Please refer to the
documentation for a detailed
explanation.
autogroup:self is marked as experimental and should be used with caution, but
we need help testing it. Experimental here means two things; first, generating
the packet filter from policies that use autogroup:self is very expensive, and
it might perform, or straight up not work on Headscale installations with a
large number of nodes. Second, the implementation might have bugs or edge cases
we are not aware of, meaning that nodes or users might gain more access than
expected. Please report bugs.
Under the hood, we have added a new datastructure to store nodes in memory. This
datastructure is called NodeStore and aims to reduce the reading and writing
of nodes to the database layer. We have not benchmarked it, but expect it to
improve performance for read heavy workloads. We think of it as, "worst case" we
have moved the bottle neck somewhere else, and "best case" we should see a good
improvement in compute resource usage at the expense of memory usage. We are
quite excited for this change and think it will make it easier for us to improve
the code base over time and make it more correct and efficient.
autogroup:member, autogroup:tagged
#2572noise config
#2658/robots.txt endpoint to avoid crawlers
#2643autogroup:self
#2789/machine/map endpoint vulnerability (#2642)474ea236d0c6d393dbcf7baa98da240ad20c1b66 Fix /machine/map endpoint vulnerability
/machine/map endpoint vulnerability (#2642)Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
…upstream has been closed and this might be a breaking change for some users. Please refer to the upstream documentation for more information on which…
Route internals have been rewritten, removing the dedicated route table in the database. This was done to simplify the codebase, which had grown unnecessarily complex after the routes were split into separate tables. The overhead of having to go via the database and keeping the state in sync made the code very hard to reason about and prone to errors. The majority of the route state is only relevant when headscale is running, and is now only kept in memory. As part of this, the CLI and API has been simplified to reflect the changes;
$ headscale nodes list-routes
ID | Hostname | Approved | Available | Serving (Primary)
1 | ts-head-ruqsg8 | | 0.0.0.0/0, ::/0 |
2 | ts-unstable-fq7ob4 | | 0.0.0.0/0, ::/0 |
$ headscale nodes approve-routes --identifier 1 --routes 0.0.0.0/0,::/0
Node updated
$ headscale nodes list-routes
ID | Hostname | Approved | Available | Serving (Primary)
1 | ts-head-ruqsg8 | 0.0.0.0/0, ::/0 | 0.0.0.0/0, ::/0 | 0.0.0.0/0, ::/0
2 | ts-unstable-fq7ob4 | | 0.0.0.0/0, ::/0 |
Note that if an exit route is approved (0.0.0.0/0 or ::/0), both IPv4 and IPv6 will be approved.
This release introduces a new policy implementation. The new policy is a complete rewrite, and it introduces some significant quality and consistency improvements. In principle, there are not really any new features, but some long standing bugs should have been resolved, or be easier to fix in the future. The new policy code passes all of our tests.
Changes
@ character.
@, like an email, this will just work.@, an
@ should be appended at the end. For example, if your user is john, it
must be written as john@ in the policy.<details>
<summary>Migration notes when the policy is stored in the database.</summary>
This section only applies if the policy is stored in the database and
Headscale 0.26 doesn't start due to a policy error
(failed to load ACL policy).
HEADSCALE_POLICY_V1=1
set. You can check that Headscale picked up the environment variable by
observing this message during startup: Using policy manager version: 1headscale policy get > policy.jsonpolicy.json and migrate to policy V2. Use the command
headscale policy check --file policy.json to check for policy errors.headscale policy set --file policy.jsonHEADSCALE_POLICY_V1.
Headscale should now print the message Using policy manager version: 2 and
startup successfully.</details>
SSH
The SSH policy has been reworked to be more consistent with the rest of the
policy. In addition, several inconsistencies between our implementation and
Tailscale's upstream has been closed and this might be a breaking change for
some users. Please refer to the
upstream documentation
for more information on which types are allowed in src, dst and users.
There is one large inconsistency left, we allow * as a destination as we
currently do not support autogroup:self, autogroup:member and
autogroup:tagged. The support for * will be removed when we have support for
the autogroups.
Current state
The new policy is passing all tests, both integration and unit tests. This does not mean it is perfect, but it is a good start. Corner cases that is currently working in v1 and not tested might be broken in v2 (and vice versa).
We do need help testing this code
server_url and base_domain to be equal
#2544headscale policy check command to check policy
#2553oidc.map_legacy_users and oidc.strip_email_domain has been removed
#2411/debug endpoint
#2420
email_verified claim in its ID
tokens, Headscale will attempt to get it from the UserInfo endpoint.…upstream has been closed and this might be a breaking change for some users. Please refer to the upstream documentation for more information on which…
Route internals have been rewritten, removing the dedicated route table in the database. This was done to simplify the codebase, which had grown unnecessarily complex after the routes were split into separate tables. The overhead of having to go via the database and keeping the state in sync made the code very hard to reason about and prone to errors. The majority of the route state is only relevant when headscale is running, and is now only kept in memory. As part of this, the CLI and API has been simplified to reflect the changes;
$ headscale nodes list-routes
ID | Hostname | Approved | Available | Serving (Primary)
1 | ts-head-ruqsg8 | | 0.0.0.0/0, ::/0 |
2 | ts-unstable-fq7ob4 | | 0.0.0.0/0, ::/0 |
$ headscale nodes approve-routes --identifier 1 --routes 0.0.0.0/0,::/0
Node updated
$ headscale nodes list-routes
ID | Hostname | Approved | Available | Serving (Primary)
1 | ts-head-ruqsg8 | 0.0.0.0/0, ::/0 | 0.0.0.0/0, ::/0 | 0.0.0.0/0, ::/0
2 | ts-unstable-fq7ob4 | | 0.0.0.0/0, ::/0 |
Note that if an exit route is approved (0.0.0.0/0 or ::/0), both IPv4 and IPv6 will be approved.
This release introduces a new policy implementation. The new policy is a complete rewrite, and it introduces some significant quality and consistency improvements. In principle, there are not really any new features, but some long standing bugs should have been resolved, or be easier to fix in the future. The new policy code passes all of our tests.
Changes
@ character.
@, like an email, this will just work.@, an
@ should be appended at the end. For example, if your user is john, it
must be written as john@ in the policy.<details>
<summary>Migration notes when the policy is stored in the database.</summary>
This section only applies if the policy is stored in the database and
Headscale 0.26 doesn't start due to a policy error (failed to load ACL policy).
HEADSCALE_POLICY_V1=1
set. You can check that Headscale picked up the environment variable by
observing this message during startup: Using policy manager version: 1headscale policy get > policy.jsonpolicy.json and migrate to policy V2. Use the command
headscale policy check --file policy.json to check for policy errors.headscale policy set --file policy.jsonHEADSCALE_POLICY_V1.
Headscale should now print the message Using policy manager version: 2 and
startup successfully.</details>
SSH
The SSH policy has been reworked to be more consistent with the rest of the
policy. In addition, several inconsistencies between our implementation and
Tailscale's upstream has been closed and this might be a breaking change for
some users. Please refer to the
upstream documentation
for more information on which types are allowed in src, dst and users.
There is one large inconsistency left, we allow * as a destination as we
currently do not support autogroup:self, autogroup:member and
autogroup:tagged. The support for * will be removed when we have support for
the autogroups.
Current state
The new policy is passing all tests, both integration and unit tests. This does not mean it is perfect, but it is a good start. Corner cases that is currently working in v1 and not tested might be broken in v2 (and vice versa).
We do need help testing this code
server_url and base_domain to be equal
#2544headscale policy check command to check policy
#2553oidc.map_legacy_users and oidc.strip_email_domain has been removed
#2411/debug endpoint
#2420
email_verified claim in its ID
tokens, Headscale will attempt to get it from the UserInfo endpoint.…upstream has been closed and this might be a breaking change for some users. Please refer to the upstream documentation for more information on which…
Route internals have been rewritten, removing the dedicated route table in the database. This was done to simplify the codebase, which had grown unnecessarily complex after the routes were split into separate tables. The overhead of having to go via the database and keeping the state in sync made the code very hard to reason about and prone to errors. The majority of the route state is only relevant when headscale is running, and is now only kept in memory. As part of this, the CLI and API has been simplified to reflect the changes;
$ headscale nodes list-routes
ID | Hostname | Approved | Available | Serving (Primary)
1 | ts-head-ruqsg8 | | 0.0.0.0/0, ::/0 |
2 | ts-unstable-fq7ob4 | | 0.0.0.0/0, ::/0 |
$ headscale nodes approve-routes --identifier 1 --routes 0.0.0.0/0,::/0
Node updated
$ headscale nodes list-routes
ID | Hostname | Approved | Available | Serving (Primary)
1 | ts-head-ruqsg8 | 0.0.0.0/0, ::/0 | 0.0.0.0/0, ::/0 | 0.0.0.0/0, ::/0
2 | ts-unstable-fq7ob4 | | 0.0.0.0/0, ::/0 |
Note that if an exit route is approved (0.0.0.0/0 or ::/0), both IPv4 and IPv6 will be approved.
This release introduces a new policy implementation. The new policy is a complete rewrite, and it introduces some significant quality and consistency improvements. In principle, there are not really any new features, but some long standing bugs should have been resolved, or be easier to fix in the future. The new policy code passes all of our tests.
Changes
@ character.
@, like an email, this will just work.@, an
@ should be appended at the end. For example, if your user is john, it
must be written as john@ in the policy.SSH
The SSH policy has been reworked to be more consistent with the rest of the
policy. In addition, several inconsistencies between our implementation and
Tailscale's upstream has been closed and this might be a breaking change for
some users. Please refer to the
upstream documentation
for more information on which types are allowed in src, dst and users.
There is one large inconsistency left, we allow * as a destination as we
currently do not support autogroup:self, autogroup:member and
autogroup:tagged. The support for * will be removed when we have support for
the autogroups.
Current state
The new policy is passing all tests, both integration and unit tests. This does not mean it is perfect, but it is a good start. Corner cases that is currently working in v1 and not tested might be broken in v2 (and vice versa).
We do need help testing this code
server_url and base_domain to be equal
#2544headscale policy check command to check policy
#2553oidc.map_legacy_users and oidc.strip_email_domain has been removed
#2411/debug endpoint
#2420
email_verified claim in its ID
tokens, Headscale will attempt to get it from the UserInfo endpoint.Fix issue where registration errors are sent correctly #2435
Nothing published for this version
Authentication flow has been rewritten #2374 This change should be transparent to users with the exception of some buxfixes that has been discovered a
oidc.map_legacy_users is now false by default
#2350Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Authentication flow has been rewritten #2374 This change should be transparent to users with the exception of some buxfixes that has been discovered a
oidc.map_legacy_users is now false by default
#2350Nothing published for this version
We would like to encourage users, and especially companies/organisations using headscale to join testing of every release. Headscale is open source an
Help beta testing:
We would like to encourage users, and especially companies/organisations using headscale to join testing of every release. Headscale is open source and it is maintained by a small group of volunteers. We need your help to ensure that the software is stable and secure. The previous release had some issues that was only found after release, we would like to avoid that in the future. This could have been avoided if companies and organisations had helped tested the release before it was released.
This release improves and fixes some long standing bugs in the authentication flow, we need help testing this release to ensure new bugs are not introduced. The interesting things would be to test the following:
oidc.map_legacy_users is now false by default
#2350Fix migration error caused by nodes having invalid auth keys #2412
Fix issue where email and username being equal fails to match in Policy #2388
Fix migration issue with user table for PostgreSQL #2367
derp.update_frequency is 0
#2368Nothing published for this version
Nothing published for this version
Nothing published for this version
The following issue _only_ affects Headscale installations which authenticate with OIDC.
The following issue only affects Headscale installations which authenticate with OIDC.
Headscale v0.23.0 and earlier identified OIDC users by the "username" part of
their email address (when strip_email_domain: true, the default) or whole
email address (when strip_email_domain: false).
Depending on how Headscale and your Identity Provider (IdP) were configured,
only using the email claim could allow a malicious user with an IdP account to
take over another Headscale user's account, even when
strip_email_domain: false.
This would also cause a user to lose access to their Headscale account if they changed their email address.
Headscale v0.24.0 now identifies OIDC users by the iss and sub claims.
These are guaranteed by the OIDC specification to be stable and unique,
even if a user changes email address. A well-designed IdP will typically set
sub to an opaque identifier like a UUID or numeric ID, which has no relation
to the user's name or email address.
Headscale v0.24.0 and later will also automatically update profile fields with OIDC data on login. This means that users can change those details in your IdP, and have it populate to Headscale automatically the next time they log in. However, this may affect the way you reference users in policies.
Headscale v0.23.0 and earlier never recorded the iss and sub fields, so all
legacy (existing) OIDC accounts need to be migrated to be properly
secured.
Headscale v0.24.0 has an automatic migration feature, which is enabled by
default (map_legacy_users: true). This will be disabled by default in a
future version of Headscale – any unmigrated users will get new accounts.
The migration will mostly be done automatically, with one exception. If your
OIDC does not provide an email_verified claim, Headscale will ignore the
email. This means that either the administrator will have to mark the user
emails as verified, or ensure the users verify their emails. Any unverified
emails will be ignored, meaning that the users will get new accounts instead
of being migrated.
After this exception is ensured, make all users log into Headscale with their account, and Headscale will automatically update the account record. This will be transparent to the users.
When all users have logged in, you can disable the automatic migration by
setting map_legacy_users: false in your configuration file.
Please note that map_legacy_users will be set to false by default in v0.25.0
and the migration mechanism will be removed in v0.26.0.
<details>
<summary>What does automatic migration do?</summary>
When automatic migration is enabled (map_legacy_users: true), Headscale will
first match an OIDC account to a Headscale account by iss and sub, and then
fall back to matching OIDC users similarly to how Headscale v0.23.0 did:
strip_email_domain: true (the default): the Headscale username matches
the "username" part of their email address.strip_email_domain: false: the Headscale username matches the whole
email address.On migration, Headscale will change the account's username to their
preferred_username. This could break any ACLs or policies which are
configured to match by username.
Like with Headscale v0.23.0 and earlier, this migration only works for users who haven't changed their email address since their last Headscale login.
A successful automated migration should otherwise be transparent to users.
Once a Headscale account has been migrated, it will be unavailable to be
matched by the legacy process. An OIDC login with a matching username, but
non-matching iss and sub will instead get a new Headscale account.
Because of the way OIDC works, Headscale's automated migration process can only work when a user tries to log in after the update.
Legacy account migration should have no effect on new installations where all
users have a recorded sub and iss.
</details>
<details>
<summary>What happens when automatic migration is disabled?</summary>
When automatic migration is disabled (map_legacy_users: false), Headscale will
only try to match an OIDC account to a Headscale account by iss and sub.
If there is no match, it will get a new Headscale account – even if there was a legacy account which could have matched and migrated.
We recommend new Headscale users explicitly disable automatic migration – but it
should otherwise have no effect if every account has a recorded iss and sub.
When automatic migration is disabled, the strip_email_domain setting will have
no effect.
</details>
Special thanks to @micolous for reviewing, proposing and working with us on these changes.
Headscale now uses the standard OIDC claims to populate and update user information every time they log in:
| Headscale profile field | OIDC claim | Notes / examples |
|---|---|---|
| email address | email |
Only used when "email_verified": true |
| display name | name |
eg: Sam Smith |
| username | preferred_username |
Varies depending on IdP and configuration, eg: ssmith, ssmith@idp.example.com, \\example.com\ssmith |
| profile picture | picture |
URL to a profile picture or avatar |
These should show up nicely in the Tailscale client.
This will also affect the way you reference users in policies.
dns.use_username_in_magic_dns configuration option
#2020,
#2279
GET /api/v1/user/{name} and GetUser have been removed in favour of ListUsers with an ID parameterRenameUser and DeleteUser now require an ID instead of a name.stable-debug container tag
#2232server_url and base_domain check. It was overly strict in some
cases. #2248--identifier in addition to --name,
usage of --identifier is recommended
#2261dns.extra_records_path configuration option #2262The following issue _only_ affects Headscale installations which authenticate with OIDC.
The following issue only affects Headscale installations which authenticate with OIDC.
Headscale v0.23.0 and earlier identified OIDC users by the "username" part of
their email address (when strip_email_domain: true, the default) or whole
email address (when strip_email_domain: false).
Depending on how Headscale and your Identity Provider (IdP) were configured,
only using the email claim could allow a malicious user with an IdP account to
take over another Headscale user's account, even when
strip_email_domain: false.
This would also cause a user to lose access to their Headscale account if they changed their email address.
Headscale v0.24.0 now identifies OIDC users by the iss and sub claims.
These are guaranteed by the OIDC specification to be stable and unique,
even if a user changes email address. A well-designed IdP will typically set
sub to an opaque identifier like a UUID or numeric ID, which has no relation
to the user's name or email address.
Headscale v0.24.0 and later will also automatically update profile fields with OIDC data on login. This means that users can change those details in your IdP, and have it populate to Headscale automatically the next time they log in. However, this may affect the way you reference users in policies.
Headscale v0.23.0 and earlier never recorded the iss and sub fields, so all
legacy (existing) OIDC accounts need to be migrated to be properly
secured.
Headscale v0.24.0 has an automatic migration feature, which is enabled by
default (map_legacy_users: true). This will be disabled by default in a
future version of Headscale – any unmigrated users will get new accounts.
The migration will mostly be done automatically, with one exception. If your
OIDC does not provide an email_verified claim, Headscale will ignore the
email. This means that either the administrator will have to mark the user
emails as verified, or ensure the users verify their emails. Any unverified
emails will be ignored, meaning that the users will get new accounts instead
of being migrated.
After this exception is ensured, make all users log into Headscale with their account, and Headscale will automatically update the account record. This will be transparent to the users.
When all users have logged in, you can disable the automatic migration by
setting map_legacy_users: false in your configuration file.
Please note that map_legacy_users will be set to false by default in v0.25.0
and the migration mechanism will be removed in v0.26.0.
<details>
<summary>What does automatic migration do?</summary>
When automatic migration is enabled (map_legacy_users: true), Headscale will
first match an OIDC account to a Headscale account by iss and sub, and then
fall back to matching OIDC users similarly to how Headscale v0.23.0 did:
strip_email_domain: true (the default): the Headscale username matches
the "username" part of their email address.strip_email_domain: false: the Headscale username matches the whole
email address.On migration, Headscale will change the account's username to their
preferred_username. This could break any ACLs or policies which are
configured to match by username.
Like with Headscale v0.23.0 and earlier, this migration only works for users who haven't changed their email address since their last Headscale login.
A successful automated migration should otherwise be transparent to users.
Once a Headscale account has been migrated, it will be unavailable to be
matched by the legacy process. An OIDC login with a matching username, but
non-matching iss and sub will instead get a new Headscale account.
Because of the way OIDC works, Headscale's automated migration process can only work when a user tries to log in after the update.
Legacy account migration should have no effect on new installations where all
users have a recorded sub and iss.
</details>
<details>
<summary>What happens when automatic migration is disabled?</summary>
When automatic migration is disabled (map_legacy_users: false), Headscale will
only try to match an OIDC account to a Headscale account by iss and sub.
If there is no match, it will get a new Headscale account – even if there was a legacy account which could have matched and migrated.
We recommend new Headscale users explicitly disable automatic migration – but it
should otherwise have no effect if every account has a recorded iss and sub.
When automatic migration is disabled, the strip_email_domain setting will have
no effect.
</details>
Special thanks to @micolous for reviewing, proposing and working with us on these changes.
Headscale now uses the standard OIDC claims to populate and update user information every time they log in:
| Headscale profile field | OIDC claim | Notes / examples |
|---|---|---|
| email address | email |
Only used when "email_verified": true |
| display name | name |
eg: Sam Smith |
| username | preferred_username |
Varies depending on IdP and configuration, eg: ssmith, ssmith@idp.example.com, \\example.com\ssmith |
| profile picture | picture |
URL to a profile picture or avatar |
These should show up nicely in the Tailscale client.
This will also affect the way you reference users in policies.
dns.use_username_in_magic_dns configuration option
#2020,
#2279
GET /api/v1/user/{name} and GetUser have been removed in favour of ListUsers with an ID parameterRenameUser and DeleteUser now require an ID instead of a name.stable-debug container tag
#2232server_url and base_domain check. It was overly strict in some
cases. #2248--identifier in addition to --name,
usage of --identifier is recommended
#2261dns.extra_records_path configuration option #22627512e236d674dc7f30e809a65d079766edafa52c Bump deprecated github actions
The following issue only affects Headscale installations which authenticate with OIDC.
Headscale v0.23.0 and earlier identified OIDC users by the "username" part of
their email address (when strip_email_domain: true, the default) or whole
email address (when strip_email_domain: false).
Depending on how Headscale and your Identity Provider (IdP) were configured,
only using the email claim could allow a malicious user with an IdP account to
take over another Headscale user's account, even when
strip_email_domain: false.
This would also cause a user to lose access to their Headscale account if they changed their email address.
Headscale v0.24.0 now identifies OIDC users by the iss and sub claims.
These are guaranteed by the OIDC specification to be stable and unique,
even if a user changes email address. A well-designed IdP will typically set
sub to an opaque identifier like a UUID or numeric ID, which has no relation
to the user's name or email address.
Headscale v0.24.0 and later will also automatically update profile fields with OIDC data on login. This means that users can change those details in your IdP, and have it populate to Headscale automatically the next time they log in. However, this may affect the way you reference users in policies.
Headscale v0.23.0 and earlier never recorded the iss and sub fields, so all
legacy (existing) OIDC accounts need to be migrated to be properly
secured.
Headscale v0.24.0 has an automatic migration feature, which is enabled by
default (map_legacy_users: true). This will be disabled by default in a
future version of Headscale – any unmigrated users will get new accounts.
The migration will mostly be done automatically, with one exception. If your
OIDC does not provide an email_verified claim, Headscale will ignore the
email. This means that either the administrator will have to mark the user
emails as verified, or ensure the users verify their emails. Any unverified
emails will be ignored, meaning that the users will get new accounts instead
of being migrated.
After this exception is ensured, make all users log into Headscale with their account, and Headscale will automatically update the account record. This will be transparent to the users.
When all users have logged in, you can disable the automatic migration by
setting map_legacy_users: false in your configuration file.
Please note that map_legacy_users will be set to false by default in v0.25.0
and the migration mechanism will be removed in v0.26.0.
<details>
<summary>What does automatic migration do?</summary>
When automatic migration is enabled (map_legacy_users: true), Headscale will
first match an OIDC account to a Headscale account by iss and sub, and then
fall back to matching OIDC users similarly to how Headscale v0.23.0 did:
strip_email_domain: true (the default): the Headscale username matches
the "username" part of their email address.strip_email_domain: false: the Headscale username matches the whole
email address.On migration, Headscale will change the account's username to their
preferred_username. This could break any ACLs or policies which are
configured to match by username.
Like with Headscale v0.23.0 and earlier, this migration only works for users who haven't changed their email address since their last Headscale login.
A successful automated migration should otherwise be transparent to users.
Once a Headscale account has been migrated, it will be unavailable to be
matched by the legacy process. An OIDC login with a matching username, but
non-matching iss and sub will instead get a new Headscale account.
Because of the way OIDC works, Headscale's automated migration process can only work when a user tries to log in after the update.
Legacy account migration should have no effect on new installations where all
users have a recorded sub and iss.
</details>
<details>
<summary>What happens when automatic migration is disabled?</summary>
When automatic migration is disabled (map_legacy_users: false), Headscale will
only try to match an OIDC account to a Headscale account by iss and sub.
If there is no match, it will get a new Headscale account – even if there was a legacy account which could have matched and migrated.
We recommend new Headscale users explicitly disable automatic migration – but it
should otherwise have no effect if every account has a recorded iss and sub.
When automatic migration is disabled, the strip_email_domain setting will have
no effect.
</details>
Special thanks to @micolous for reviewing, proposing and working with us on these changes.
Headscale now uses the standard OIDC claims to populate and update user information every time they log in:
| Headscale profile field | OIDC claim | Notes / examples |
|---|---|---|
| email address | email |
Only used when "email_verified": true |
| display name | name |
eg: Sam Smith |
| username | preferred_username |
Varies depending on IdP and configuration, eg: ssmith, ssmith@idp.example.com, \\example.com\ssmith |
| profile picture | picture |
URL to a profile picture or avatar |
These should show up nicely in the Tailscale client.
This will also affect the way you reference users in policies.
dns.use_username_in_magic_dns configuration option
#2020,
#2279
GET /api/v1/user/{name} and GetUser have been removed in favour of ListUsers with an ID parameterRenameUser and DeleteUser now require an ID instead of a name.stable-debug container tag
#2232server_url and base_domain check. It was overly strict in some
cases. #2248--identifier in addition to --name,
usage of --identifier is recommended
#2261dns.extra_records_path configuration option #2262Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per quarter.