Headscale Files

Minimum supported Tailscale client version: v1.64.0

Changes

• Expire nodes with a custom timestamp #2828
• Fix issue where node expiry was reset when tailscaled restarts #2875
• Fix OIDC authentication when multiple login URLs are opened #2861
• Fix node re-registration failing with expired auth keys #2859
• Remove old unused database tables and indices #2844 #2872
• Ignore litestream tables during database validation #2843
• Fix exit node visibility to respect ACL rules #2855
• Fix SSH policy becoming empty when unknown user is referenced #2874
• Fix policy validation when using bypass-grpc mode #2854
• Fix autogroup:self interaction with other ACL rules #2842
• Fix flaky DERP map shuffle test #2848
• Use current stable base images for Debian and Alpine containers #2827

Upgrade

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.

Backup Your Database

Always backup your database before upgrading. Here's how to backup a SQLite database:

:::bash
# 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

Changelog

• [abed53] Document how to restrict access to exit nodes per user/group
• [d23fa2] Fix flaky TestShuffleDERPMapDeterministic by ensuring deterministic map iteration (#2848)
• [0a43aa] Use Debian 12 as minimum version for the deb package
• [4bd614] Use current stable base images for Debian and Alpine
• [785168] changelog: prepare for 0.27.1
• [19a333] changelog: set 0.27 date (#2823)
• [af2de3] chore: fix autogroup:self with other acl rules (#2842)
• [02c7c1] cli: only validate bypass-grpc set policy (#2854)
• [5a2ee0] db: add comment about removing migrations
• [28faf8] db: add defensive removal of old indicies
• [456a5d] db: ignore _litestream tables when validating (#2843)
• [ddbd3e] db: remove all old, unused tables (#2844)
• [f9bb88] expire nodes with a custom timestamp (#2828)
• [5cd15c] fix: make state cookies valid when client uses multiple login URLs
• [3bd4ec] fix: preserve node expiry when tailscaled restarts
• [3455d1] hscontrol/db: fix RenameUser to use Updates()
• [4a8dc2] hscontrol/state,db: preserve node expiry on MapRequest updates
• [4728a2] hscontrol/state: allow expired auth keys for node re-registration
• [ddd31b] hscontrol: use Updates() instead of Save() for partial updates
• [773a46] integration: add test to replicate [#2862]
• [84fe3d] integration: reduce TestAutoApproveMultiNetwork matrix to 3 tests (#2815)
• [d9c3ea] matcher: Add func for comparing Dests and TheInternet
• [f658a8] mkdocs: 0.27.1
• [c649c8] policy: Reproduce exit node visibility issues
• [21e3f2] policy: fix issue where non existent user results in empty ssh pol
• [a28d9b] policy: reproduce 2863 in test
• [d7a43a] state: use AllApprovedRoutes instead of SubnetRoutes
• [202421] types: Distinguish subnet and exit node access
• [bd9cf4] types: NodeView CanAccess uses internal
• [1c0bb0] types: split SubnetRoutes and ExitRoutes