ts destination-class

Show and manage a destination class: a named set of hosts that network access rules and workspace network lists name instead of listing the hosts themselves. Use one for a group of hosts several rules share.

Usage

ts destination-classes [--csv] [--no-trunc]
ts destination-class <id>
ts destination-class <id> <property>
ts destination-class new --file=<path>
ts destination-class set <id> <property> <value>
ts destination-class set <id> --file=<path>
ts destination-class delete <id> [--force]

Description

A network access rule names classes by key in its classes, and a workspace's network list names them under Destination Classes on the workspace's Network tab. The server expands a class into its hosts when it serves the policy, so a change to a class changes every rule and list that names it. The Administration site shows classes in the Destination Classes table under Workspaces → Policy, on the Network tab.

The server ships built-in classes, such as modelApi, packageRegistry, gitRemote, exfiltration, and sharedHosting, whose hosts are updated with server releases. ts destination-classes lists the built-in classes first, then yours by name, each with its key, name, number of hosts, whether it is built in, and its ID. A built-in class has no ID, shown as -, so the singular forms cannot read, change, or delete it; ts destination-classes --format=json shows its hosts. Some built-in classes also hold readOnlyHosts, which a rule that allows the class without a proxy reaches for reading only.

The Document

{
  "id": "7e1d4c9b-2a3f-4b8e-9d6c-5f0a1b2c3d4e",
  "key": "corp-services",
  "name": "Corporate services",
  "description": "Internal services every session may reach.",
  "hosts": ["git.corp.example.com", "*.pkg.example.com"],
  "builtIn": false,
  "readOnlyHosts": []
}

• key — What rules and lists name. Letters, digits, ., _, and -, up to 128 characters. It cannot match a built-in class's key or another class's, ignoring case, and cannot change after the class is created.
• name — The display name. Required.
• description — Optional.
• hosts — Whole host names, at least one. One containing * is a wildcard, and *.example.com does not match example.com itself. A class takes no paths, and no host of the built-in sharedHosting class; to read from one publisher's path there, name it in a read rule.
• id, builtIn, and readOnlyHosts are printed but not written.

Reading and Writing

ts destination-class <id> prints the document as the server sends it, compact on one line, and set --file takes the same shape back. new and set read the document from --file; - reads standard input. ts destination-class <id> <property> reads one field, and set <id> <property> <value> writes one, such as name or description; hosts is a list, which only --file changes. After an accessor write, ts reads the field back and fails if the server kept another value.

new prints only Created destination class; find the new ID with ts destination-classes, or under --format=json as result.entity.id. delete confirms first, and is refused while any network access rule or workspace network list names the class, because a rule that lost its destinations would stop applying. The refusal says how many still name it; remove the class from them first. A delete of an ID no class has reports success. Creating, changing, and deleting a class are recorded in the audit log. Every form, reading included, needs a Server Administrator.

Options

Flag	Description	Default/Values	Notes
--file	JSON document to send.	PATH, or - for standard input	Required by new. set needs it only for the whole-document form.
--force, -f	Delete without confirming.		delete only. Required when there is no terminal.
--csv	Tab-separated output, nothing truncated.		ts destination-classes only.
--no-trunc	Do not truncate columns.		ts destination-classes only.

Examples

# Every class, built-in first
ts destination-classes

# The hosts of every class, built-in ones included
ts destination-classes --format=json

# A class of internal services, and a rule that allows it
cat <<'JSON' | ts destination-class new --file=-
{ "key": "corp-services", "name": "Corporate services",
  "hosts": ["git.corp.example.com", "*.pkg.example.com"] }
JSON
cat <<'JSON' | ts network-rule new --file=-
{ "name": "allow-corp-services", "classes": ["corp-services"],
  "ports": ["443"], "action": "allow" }
JSON

# Rename it; the key that rules name stays
ts destination-class set 7e1d4c9b-2a3f-4b8e-9d6c-5f0a1b2c3d4e name "Corporate services (HQ)"

# Add a host: hosts is a list, so edit the document
ts destination-class 7e1d4c9b-2a3f-4b8e-9d6c-5f0a1b2c3d4e | jq . > class.json
$EDITOR class.json
ts destination-class set 7e1d4c9b-2a3f-4b8e-9d6c-5f0a1b2c3d4e --file=class.json

# A host added to a class reaches every rule that names it, deny rules
# included. Check which rules name the class before you change it.
ts network-rules --no-trunc | grep corp-services

Exit Codes

0 on success, including a delete of an ID no class has. -1 when the server refuses the document: a missing, malformed, taken, or changed key, a missing name, no hosts, a host that is not a host name, a path, or a shared-hosting host. -1 also when a delete is refused because a rule or workspace list names the class, when an accessor write reads back another value, and when you decline the delete prompt. -2 when the accessor names a list, and when set is given both a property and --file. -4 when no account is signed in. -5 when the account is not a Server Administrator. -6 when the ID is not a GUID or no class of yours has it, when the --file path does not exist, and when a property is not a field of the document.

Related Commands

• ts network-rule — The rules whose classes name destination classes.
• ts policy — The launch policy the rules are served in.
• ts audit — Who changed a class, and when.