Appearance

ts join-link ​

Issue the link a new server joins this cluster with, then pass it to the new server's installer. It is the same link the Administration site's Generate Join Link issues, under Infrastructure → Servers.

Usage ​

text
ts join-link [--roles=ROLES] [--expires-in=MINUTES]

Description ​

ts join-link prints the link on its own line, then when it expires and the roles it allows. Run the installer on the new server with the link and the roles that server is to have; an interactive installer asks for the roles when you leave them out:

bash
TurboProvisioner --join-link "<link>" --roles Application

The link carries the Controller's address, a one-time enrollment token and its expiry, and the pin of the Controller's internal TLS certificate, which lets the new server fetch the cluster certificate over a pinned connection. The installer unpacks it into --controller-url, --enrollment-token and --internal-tls-pin, and any of those you pass yourself wins over the link. The installer refuses a link that has expired.

  • One use. The first server to join with the link uses it up, so issue one link per server.
  • Expiry. A link lasts an hour unless --expires-in says otherwise, from 1 to 1,440 minutes.
  • Roles. A link lets a server join as Hub, Portal and Application unless --roles names fewer. The server joins with the roles its installer asks for that the link allows; any other role it asks for is dropped, and a server that asks for none of them is refused. A new server never joins as the Controller.

The link names the server domain, so set domain with ts settings before issuing one. The Controller issues the enrollment, so it has to be running. Each link issued is recorded in the audit log as NodeEnrollmentCreated, with the acting administrator, the roles, and the expiry.

WARNING

The link carries a credential. Treat it as a password: keep it out of tickets and chat, keep its lifetime short, and limit --roles to what the new server needs.

Options ​

FlagDescriptionDefault/ValuesNotes
--rolesThe roles the new server may join as.Hub, Portal, Application, comma-separatedAll three when omitted. Any other role is refused.
--expires-inMinutes until the link expires.1 to 1440; default 60

Examples ​

bash
# A link for a new Application server, valid for 30 minutes
ts join-link --roles Application --expires-in 30

# Only the link, for a script that provisions the new server
ts join-link --roles Hub,Portal | head -n 1

# Who issued join links, and when?
ts audit --event=NodeEnrollmentCreated
bash
# The installer's --roles must include one of the link's roles. This link
# allows Application only, so a server installed with --roles Hub,Portal is
# refused when it joins.
ts join-link --roles Application

Output ​

text
https://turbo.example.com/admin/join?key=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...&expires=2026-10-21T15%3A30%3A12Z&pin=8D2F6A0C...
Expires today 15:30. Used once, by a server joining as Application.

The token and pin are shortened here. The second line gives the expiry in this machine's time zone. With --format=json, the result carries joinLink, expiresAt and roles.

Exit Codes ​

0 on success. -1 when the server refuses the request: --roles names a role other than Hub, Portal or Application, --expires-in is outside 1 to 1,440, the server domain is not set, or the Controller does not issue the enrollment. -3 when the server cannot be reached. -4 when no account is signed in. -5 when the account is not a Server Administrator.

  • ts server — The servers in the cluster, including one that has just joined.
  • ts settings — domain, the address the link names.
  • ts audit — Who issued join links, and when.

Turbo.net © 2025