Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.siderolabs.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide explains how to rotate SideroLink join tokens. Join tokens are the secret used to authenticate Talos machines’ gRPC requests when they first establish a WireGuard tunnel connection to Omni. If the token is compromised it can be revoked and replaced with the new one.

​
When token rotation works

When a machine connects to Omni for the first time, it uses a shared join token tied to your Omni account. This token is used by all new machines during registration. After the initial connection, Omni generates a unique, short-lived token for each machine. When Talos is installed to disk, this token is persisted. If you revoke the shared token:
  • Machines with persisted unique tokens (installed to disk) will remain connected.
  • Machines still using the shared token will be disconnected.
Talos versions earlier than 1.6 do not support unique tokens.
If Omni is started with --join-tokens-mode=legacy, unique machine tokens are not generated. In this mode, join token rotation is not supported.

​
Steps to rotate join tokens

You can rotate join tokens using either the CLI or the Omni UI:
To rotate a join token using the CLI:
  1. Create a new join token. Replace <new-token-name> with your preferred name:
omnictl jointoken create <new-token-name>
  1. List all join tokens and their IDs:
omnictl jointoken list
  1. If you are rotating the default token, set the new token as default. Replace <new-join-token-id> with the ID of the new token:
omnictl jointoken make-default <new-join-token-id>
  1. Revoke the old token. Replace <old-join-token-id> with the ID of the token you want to revoke:
omnictl jointoken revoke <old-join-token-id>
If warnings are shown and you proceed anyway, the listed machines will be disconnected after the next restart of Omni or the affected machines.
If it is safe to revoke the token, the operation will proceed without confirmation.
After rotating the token, copy the new token and use it for future machine registrations.