Updates and release trust
System → Updates manages the release cache and the gateway’s own update policy. Managed servers use the same cache for their roles.
Built-in trust from v2.18.1
Section titled “Built-in trust from v2.18.1”v2.18.1 includes both release-signing public keys in the gateway and bootstrap: primary 03ea7f6bcef4ab19 and reserve e740c848903fec85. Signed manifests and the release channel can now be authenticated against these built-in keys. The bootstrap refuses an unsigned release unless GATEWAY_ALLOW_UNSIGNED=1 is explicitly set for a legacy release.
The release cache marks a release signed by a built-in key as signed. A release signed only by an unknown key still needs manual administrator acceptance and does not qualify for automatic updates. Automatic updates remain opt-in, respect the configured delay and maintenance window, and are not used by development builds.
Upgrading from v2.18.0
Section titled “Upgrading from v2.18.0”No release-signing public keys are built into v2.18.0. It cannot authenticate the site’s release signatures against a built-in key. An archive enters the cache as unsigned and an administrator must accept it manually. The auto policy will not accept a release in this state.
For this version, update by uploading an archive in System → Updates and reviewing it manually, or use the installer. The v2.18.0 bootstrap checks SHA256 values, but its own release-key list is also empty: it does not verify the manifest signature. Do not describe these checksum checks as authenticated publisher verification.
After installing v2.18.1, subsequent signed releases and channel refreshes can be verified against its built-in keys. Publishing signed files alone does not add keys to an older running gateway.
Release cache
Section titled “Release cache”You can upload an archive in resumable parts or fetch a release from the site. The cache checks file checksums and evaluates signatures against its trust configuration. It retains releases used by installed roles.
From v2.19.0, site downloads also fetch the server agent and role binaries for managed-server architectures, checking each against the signed manifest. Existing cached releases are topped up when necessary. Short link drops are retried during uploads and site downloads.
The gateway’s own release checks and downloads follow own-traffic privacy settings: use an eligible tunnel by default, or wait if none is up. Direct WAN downloads require an explicit opt-in. Release mirrors on the LAN, mesh or loopback do not require a tunnel.
The release file set includes BUILDINFO, RELEASE_NOTES.md, both installers, compressed component binaries, UPSTREAM_SHA256SUMS, SHA256SUMS and its detached signature. SHA256SUMS covers all release files except itself and its signature, including UPSTREAM_SHA256SUMS. The latter records the decompressed hash of every gzip binary.
Download failures, checksum mismatches and unknown trust are not interchangeable: do not bypass an integrity failure by manually accepting an archive. Obtain public keys through an independent operator/developer channel rather than trusting a key downloaded only from the same site as the files.
Self-update sequence
Section titled “Self-update sequence”The built-in updater is distinct from the shell installer’s service-state rollback:
- From v2.18.2, preparation hashes the installed gatewayd unit and helper scripts and compares them with the release’s
BUILDINFO.installer_hash. A checkbox alone cannot satisfy this check. Matching files need no refresh. - The candidate binary checks itself in a sandbox using a copy of the database.
- A watcher written by the running version restarts the service.
- During the confirmation window it checks the API, DNS, fail-closed tables and processes, plus external dependencies that worked before the update: tunnels, WAN connectivity and federation peers.
- In a watcher written by v2.18.2 or newer, external failures during the initial grace period—one tenth of the window, at most 60 seconds—are logged without extending it. Afterward, only a previously unseen external failure extends the window. Recovering links do not count as new failures; external failures do not themselves cause rollback.
- A failed confirmation window rolls back the binary and database snapshot, carrying over security data written during the window.
Take a backup and retain console access before upgrading a gateway carrying traffic. A rollback of the website’s latest release does not automatically downgrade gateways that already installed a newer version.
Refreshing installer-managed files
Section titled “Refreshing installer-managed files”From v2.18.2, System → Updates → Refresh them from vX runs that cached release’s install-gateway.sh --refresh after checking it against SHA256SUMS. It updates only the unit and helper scripts: no package installation, configuration changes or restart. The refresh succeeds only when the resulting files match the release’s hash. The API is POST /api/v1/system/update/installer-refresh with a JSON version field.
For a release cached by an older gateway, missing metadata fields are recovered from the original cached BUILDINFO. Automatic updates can proceed when the installed files already match, subject to the existing trust and scheduling policy.
Moving from v2.18.2 to v2.19.0
Section titled “Moving from v2.18.2 to v2.19.0”- Cache the signed v2.19.0 release. The running v2.18.2 gateway fetches it using its existing download behaviour.
- Run Refresh them from v2.19.0. The pre-start salvage helper changed, so this release genuinely requires installer-file refresh; preparation checks the resulting hash.
- Prepare and apply the update, then verify the new own-traffic settings. With no VPN routing policy, future internet release checks/downloads wait unless direct downloads are enabled. An uploaded archive or local mirror is another option.
- Review WAN probe targets and DNS fallback needs. First-hop-only checks do not prove the ISP beyond that router is reachable.
Migration 077 adds the Tailscale telemetry preset, disabled by default. The release’s downgrade threshold is v2.19.0. A rollback to v2.18.2 is supported inside the updater’s confirmation window by restoring its database snapshot; replacing only the binary is not a supported downgrade.
Moving from v2.18.1 to v2.18.2
Section titled “Moving from v2.18.1 to v2.18.2”The unit and helper scripts are unchanged, and both releases have installer_hash starting 1766f722. However, v2.18.2’s original BUILDINFO contains the known build-tool error requires_installer: true. The older v2.18.1 updater may ask once for I ran the installer’s refresh; ensure the refresh actually ran with GATEWAY_REFRESH=1. The new hash-based checks apply once v2.18.2 is running.
The watcher comes from the old running version, so this transition can still repeatedly extend its confirmation window as tunnels recover. Confirm now ends that window. See the unmodified upstream release notes.
Policy and scheduling
Section titled “Policy and scheduling”| Setting | Behavior |
|---|---|
notify |
Report available updates for operator review. |
manual |
Let the administrator choose when to install. |
auto |
Opt-in installation of releases trusted by a built-in key, after the configured delay and within the maintenance window. Requires v2.18.1 or newer. |
| Check cadence | Daily or weekly; from v2.19.0, never disables contact with the release site and is available with manual policy. |
| Version selection | Follow latest, pin a version, or skip a version. |
Server-role changes have their own per-server maintenance windows. Neither publishing a website release nor refreshing its signed channel updates a running node by itself.
Signed release channel
Section titled “Signed release channel”/releases/channel.json identifies latest, published_at, signed_at, expires_at and revoked_keyids. Its detached signature is /releases/channel.json.sig. Signatures use Ed25519 over the exact file bytes, with one ed25519 <keyid> <base64-signature> line per signing key.
The publication process refreshes the channel signature every seven days with a 21-day validity period. Refreshing changes only signed_at and expires_at; it does not create a new release. Expiry is a warning that the channel may have stopped updating, not evidence that the installed gateway has failed.
Upgrade changes from v2.17.0
Section titled “Upgrade changes from v2.17.0”- Database migrations 061–077 run forward when upgrading to v2.19.0. From v2.16.0, migration 060 for tunnel-bound proxies is also new.
- Server management remains disabled until an administrator enables it; sign-in is required.
- Fresh installations have no relay until one is set up. Headscale is off and relay mode is
noneby default in the bootstrap. - Chain Routing is retired; use multi-hop routing policies. Old chain-routing state is cleaned up at boot.
- Encrypted LUKS2 storage can hold backups and keys; tunnel keys remain outside it so VPN connectivity can come up before unlocking.
Related
Section titled “Related”- Installation — shell installation and update commands.
- Server management — role updates and job controls.
- Release notes — changes and downloadable artifacts.
- Backup — recovery preparation.