ts group

Show, create, rename, or delete a user group, and change who is in it: accounts one at a time, or every member of another group at once by nesting it. Reach for groups first when granting access, since permissions attach to a group rather than to a person.

Usage

ts groups [--csv] [--no-trunc]
ts group [print | members] <group>
ts group new <name> [--description=TEXT]
ts group rename <group> <new-name> [--description=TEXT]
ts group delete <group> [--force]
ts group add <group> <login>
ts group remove <group> <login>
ts group nest <group> <member-group>
ts group unnest <group> <member-group>

Description

ts groups lists every group with its description, whether it is built in, and its ID. A group from an identity source with a login prefix is listed after the prefix and a backslash, as in CORP\Sales, because a group's name is unique only within its source. Every other form takes a group by that spelling, by its plain name when only one source has a group of that name, or by its ID. A name two sources share is refused with a request to qualify it.

ts group <group> and ts group members <group> print the same thing: the group's name, description and built-in flag, its member accounts, and the groups nested in it.

Which Groups You Can Change

new makes a group in the built-in Internal source. Only such a group, one an administrator made, can be renamed or deleted. The others keep what they came with:

• Built-in groups (Administrators, Analysts, Anonymous Users, Everyone) keep their names and cannot be deleted, because the server's own rules refer to them.
• A directory's or provider's groups are named by their identity source, and a member's next sign-in would bring a deleted one back. Their members are the source's to decide at each sign-in, so add, remove, nest and unnest refuse them as the group being changed.
• Guest groups, Anonymous Users and the group each client or deployment keeps for its guests, hold guests rather than accounts, so they take no members and nest in no group. A guest group goes when its client or deployment stops taking guests.
• Everyone holds every account implicitly. It takes no members, and nests in no group, since nesting it in Administrators would make every account an administrator.

rename changes the name, and the description when you pass --description; without it the description is kept, and --description="" clears it. A name another group already has is refused.

Members and Nested Groups

add and remove change one account's membership. Name the account by its login name, by its login after its source's login prefix and a backslash, or by the ID ts users lists.

nest <group> <member-group> makes every member of <member-group> a member of <group>, and unnest ends that. The member group can be any group but Everyone and a guest group, including a directory's group, which is how a directory's people gain the access of a group you manage. A group cannot be its own member, and a nesting that would make a loop is refused.

Adding a membership that already exists, or removing one that does not, changes nothing. A change that would leave Administrators with no enabled member is refused: removing its last enabled member, unnesting the group that holds them, or deleting such a group.

Creating, renaming, and deleting groups and every membership change are recorded in the operator audit log with the acting administrator, so ts audit can answer when someone gained access and who gave it. Membership in the built-in Administrators group is what ts itself requires for administrative commands; see Signing In.

Options

Flag	Description	Default/Values	Notes
--description	Description of a new group, or a renamed one's new description.		new and rename. On rename, omit it to keep the description; pass "" to clear it.
--force, -f	Delete without confirming.		delete only. Required when there is no terminal.
--csv	Tab-separated output, nothing truncated.		ts groups only.
--no-trunc	Do not truncate columns.		ts groups only.

Examples

# Every group
ts groups

# Who is in this one?
ts group members "QA Team"

# A new group
ts group new "Build Agents" --description="Automation accounts for CI"

# Rename it, keeping its description
ts group rename "Build Agents" "CI Accounts"

# Grant and revoke by membership
ts group add "QA Team" jsmith
ts group remove "QA Team" jsmith

# Give a directory group's members the access of a group you manage
ts group nest "QA Team" 'CORP\Testers'
ts group unnest "QA Team" 'CORP\Testers'

# Remove a group entirely
ts group delete "CI Accounts" --force

# In a POSIX shell a backslash is an escape character. Quote a qualified
# name, or the shell hands ts "CORPTesters".
ts group nest "QA Team" CORP\Testers

Output

NAME             DESCRIPTION                                          BUILT-IN  ID
Administrators   Administrators group.                                yes       0cf2d619-ee66-4b09-9e9a-be5a6bd6d049
Analysts         Users with permission to access server reports.      yes       5d1e8c2a-7b34-4f90-a6e1-2c9b0d7f4e13
Anonymous Users  Guests: people using the server without an account.  yes       d9a4e0b4-5972-4277-8774-06805e2cc80a
CORP\Testers                                                          no        4c7e1a90-3b2d-4f6e-9a18-5d0c2b7e3f41
Everyone         All users.                                           yes       3b7bbafc-4f12-4b4b-b068-80830e1b66e8
QA Team          Test engineers.                                      no        8a1c7e42-90bb-4d15-a3f7-6c2e0b9d4517

Name:          QA Team
Description:   Test engineers.
Built-in:      no
Members:       2
  jsmith
  alice
Member groups: 1
  CORP\Testers

Exit Codes

0 on success, including an add or a removal that changes nothing. -1 when the server refuses the change: a rename or delete of a group an administrator did not make, a membership change to a group whose members are fixed, a name another group has, a nesting that is a loop or names Everyone or a guest group, a change that would leave Administrators with no enabled member, or a name two sources share. -4 when no account is signed in. -5 when the account is not a Server Administrator. -6 when the group, the member group, or the account does not exist.

Related Commands

• ts user — The accounts that go into groups.
• ts identity-source — The source each group belongs to.
• ts workspace — Where group permissions are applied.
• ts audit — Who changed a group's membership, and when.