Minimum supported Tailscale client version: v1.64.0

Database integrity improvements

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

DERPMap update frequency

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.

Autogroups

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.

Node store (in memory database)

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.

BREAKING

• Remove support for 32-bit binaries #2692
• Policy: Zero or empty destination port is no longer allowed #2606
• Stricter hostname validation #2383
  • Hostnames must be valid DNS labels (2-63 characters, alphanumeric and hyphens only, cannot start/end with hyphen)
  • Client Registration (New Nodes): Invalid hostnames are automatically renamed to invalid-XXXXXX format
    • my-laptop → accepted as-is
    • My-Laptop → my-laptop (lowercased)
    • my_laptop → invalid-a1b2c3 (underscore not allowed)
    • test@host → invalid-d4e5f6 (@ not allowed)
    • laptop-🚀 → invalid-j1k2l3 (emoji not allowed)
  • Hostinfo Updates / CLI: Invalid hostnames are rejected with an error
    • Valid names are accepted or lowercased
    • Names with invalid characters, too short (<2), too long (>63), or starting/ending with hyphen are rejected

Changes

• Database schema migration improvements for SQLite #2617
  • IMPORTANT: Backup your SQLite database before upgrading
  • Introduces safer table renaming migration strategy
  • Addresses longstanding database integrity issues
• Add flag to directly manipulate the policy in the database #2765
• DERPmap update frequency default changed from 24h to 3h #2741
• DERPmap update mechanism has been improved with retry, and is now failing conservatively, preserving the old map upon failure. #2741
• Add support for autogroup:member, autogroup:tagged #2572
• Fix bug where return routes were being removed by policy #2767
• Remove policy v1 code #2600
• Refactor Debian/Ubuntu packaging and drop support for Ubuntu 20.04.

Changelog

• 047dbda136d0810839abcd09944371f647ac9f31 Add FAQ on how to disable log submission
• 2a1392fb5ba99bae65f64c81cef32bb624d81a66 Add healthcheck to container docs
• 46477b8021484bce63d84f4b2f0bad245c16bc3f Downgrade completed broadcast message to debug
• ed38d00aaa061f8661bd373f3bee3d777c501e25 Fix autogroup:self alternative example
• c97d0ff23dd86492bcb6c9e31339527e4651129a Fix fatal error on missing config file by handling viper.ConfigFileNotFoundError
• 8becb7e54a6b565013aeff2feee5e5d639c564aa Mention explicitly that @ is only required in policy
• 8010cc574ea309728f5c7d3fd1cb08252f0111f5 Remove outdated hint about an empty config file
• 2c9e98d3f513d492ac302a5ad108ecd29668f1d9 fix: guard every error statement with early return (#2810)
• 66826232ffad624ba25365fceb6e72a3465e3655 integration: add tests for api bypass (#2811)
• 2bf12004830e89887f455fccc835e16d851a0f48 policy: fix autogroup:self propagation and optimize cache invalidation (#2807)
• 1cdea7ed9bfc589b57dd6282d537bd07967e48cd stricter hostname validation and replace (#2383)