ts server

View and set one server's settings, hostname and tags, take it out of service or delete it, and act on its Application Server. Reach for stop-sessions or decommission before maintenance or retirement, so the server's users are not cut off mid-session.

Usage

ts servers [--role=ROLE] [--csv] [--no-trunc]
ts server <name> [<property> [<value>]]
ts server set <name> <property> <value>
ts server <name> hostname [<hostname>]
ts server <name> tags
ts server tag <name> <tag>[=<value>]
ts server untag <name> <tag>[=<value>] [--force]
ts server stop-sessions <name>
ts server resume-sessions <name>
ts server decommission <name> [--force]
ts server cancel-decommission <name>
ts server delete <name> [--force]
ts server pull-images <name>
ts server clear-image-cache <name> [--force]
ts server delete-unallocated-profiles <name> [--force]

Description

A Turbo Server deployment can be several machines, each running some of the roles Controller, Hub, Portal, Broker and Application. ts servers lists them with their hostnames and roles; --role narrows the list to one role, and a role name it does not recognize lists every server. The same servers appear in the Administration site under Infrastructure → Servers.

ts server <name> names a server in any case and prints its name, hostname, roles, state, tags and every setting. The state is Accepting new user sessions, Not accepting new user sessions, Decommissioning with its active user sessions and in-flight launches, or Being deleted.

Settings

Naming a property gets that one value, (unset) when it has none; naming a property and a value sets it, as does set. These are per-server settings, distinct from the deployment-wide ones in ts settings. Each value is checked before it is saved: a boolean takes true or false, a count or size takes a whole number that is not negative, hub-cdn-url takes an http(s) URL, and turning off both ssl-tls12-enabled and ssl-tls13-enabled is refused. An empty value clears the setting to its default.

hub-storage-root and migrate-hub-storage-path are refused: a Hub's storage moves only from its server's page in the Administration site, which checks the new location first. Every change is recorded in the audit log with the server and property named; a value equal to the stored one records nothing.

Hostname and Tags

hostname is the address other Turbo servers reach the server at. Setting it stops the server's own reports changing it; a pasted scheme or path is removed. Set it to "" to clear it, and the server reports its address again within about 30 seconds; until then, traffic from other servers may fail, so clearing asks first. The Controller server does not report its own address, so its hostname cannot be cleared: set a new one instead.

Tags are the name and value labels that Server Tag Rules match to choose where an application runs. A server can carry several values of one tag. tag adds one, and a pair the server already carries is left as it is. untag deletes the value you give, or every value of the tag when you give none, and asks first. To change a value, untag the old one, then tag the new one. ts server <name> tags prints the tags one a line, in the form tag takes.

Taking a Server Out of Service

stop-sessions stops the server accepting new user sessions, and resume-sessions lets it accept them again; resuming is refused while the server is being decommissioned. decommission stops new user sessions and deletes the server once its user sessions end. cancel-decommission keeps the server and gives it back the new-sessions setting it had before, unless deletion has started. delete deletes the server now and ends its user sessions immediately; when the Controller is still completing its cleanup, it prints that the server is being deleted.

decommission and delete ask first and show the active user sessions and in-flight launches they affect. The Controller server is never decommissioned or deleted. Each change is recorded in the audit log.

Application Server Actions

These act on the server's Application Server, as its page in the Administration site does:

• pull-images starts pulling every image the server pre-caches; the pull goes on in the background. It is refused, with the Application Server's reason, when the pull would not start.
• clear-image-cache asks first, then removes every cached image; the next pass pulls them again, which can be slow and fetches every image from the Hub. It is refused while a pre-cache pass is running.
• delete-unallocated-profiles asks first, then deletes the Windows profiles no session is using. A profile that cannot be deleted is listed with its account and reason, and the command fails. When Windows denies permission, run the Application Server from an Administrator terminal and try again.

Each is refused for a server without the Application role, or one with no hostname yet.

Options

Flag	Description	Default/Values	Notes
--role	Show only servers with this role.	Controller, Hub, Portal, Broker, Application	ts servers only.
--force, -f	Skip the confirmation prompt.		untag, decommission, delete, clear-image-cache, delete-unallocated-profiles, and clearing hostname. Required when there is no terminal.
--csv	Tab-separated output, nothing truncated.		ts servers only.
--no-trunc	Do not truncate columns.		ts servers only.

Examples

# Every machine
ts servers

# Just the application servers
ts servers --role=Application

# One machine and everything about it
ts server app01

# Read one setting
ts server app01 ssl-hsts

# Change it
ts server app01 ssl-hsts true

# Keep 20 temporary user profiles ready
ts server app01 temp-user-profile-pool-count 20

# Pin the address other servers reach it at
ts server app01 hostname app01.example.com

# Move a server from one region to another
ts server untag app01 region=east
ts server tag app01 region=west

# Drain a server before maintenance, then bring it back
ts server stop-sessions app01
ts server resume-sessions app01

# Retire a server once its users have finished
ts server decommission app01

# Pre-cache images now instead of waiting for the next pass
ts server pull-images app01

# delete ends every user session on the server at once. Prefer decommission,
# which waits for them to end.
ts server delete app01 --force

Exit Codes

0 on success. -1 when the command or the server refuses: a setting that is not a server setting, a value of the wrong kind, a Hub storage setting, both TLS versions off, a hostname that is not a host name or address, clearing the Controller's hostname, decommissioning or deleting the Controller, resuming a server being decommissioned, canceling a decommission that is not pending or whose deletion has started, an Application Server action on a server without the Application role or with no hostname, a pull that would not start, clearing the image cache during a pre-cache pass, a profile that could not be deleted, or a question declined or not asked because there is no terminal and no --force. -4 when no account is signed in. -5 when the account is not a Server Administrator. -6 when no server has that name, when the property you read is not a server setting, and when untag names a tag the server does not have.

Related Commands

• ts settings — Deployment-wide settings.
• ts status — Whether a server is actually answering.