# Using Groups

This chapter explains how to create groups and discusses different ways to use them.

## About Groups

An AFS group is a list of specific users that you can place on access control lists (ACLs). Groups make it much easier to maintain ACLs. Instead of creating an ACL entry for every user individually, you create one entry for a group to which the users belong. Similarly, you can grant a user access to many directories at once by adding the user to a group that appears on the relevant ACLs.

AFS client machines can also belong to a group. Anyone logged into the machine inherits the permissions granted to the group on an ACL, even if they are not authenticated with AFS. In general, groups of machines are useful only to system administrators, for specialized purposes like complying with licensing agreements your cell has with software vendors. Talk with your system administrator before putting a client machine in a group or using a machine group on an ACL.

machines as members of groups
groups machines as members

To learn about AFS file protection and how to add groups to ACLs, see Protecting Your Directories and Files.

### Suggestions for Using Groups Effectively

There are three typical ways to use groups, each suited to a particular purpose: private use, shared use, and group use. The following are only suggestions. You are free to use groups in any way you choose.

- Private use: you create a group and place it on the ACL of directories you own, without necessarily informing the group's members that they belong to it. Members notice only that they can or cannot access the directory in a certain way. You retain sole administrative control over the group, since you are the owner.

  private use of group
  groups private use

  The existence of the group and the identity of its members is not necessarily secret. Other users can see the group's name on an ACL when they use the fs listacl command, and can use the pts membership command to display + the groups to which they themselves belong. You can, however, limit who can display the members of the group, as described in Protecting Group-Related Information.

- Shared use: you inform the group's members that they belong to the group, but you are the group's sole owner and administrator. For example, the manager of a work group can create a group of all the members in the work group, and encourage them to use it on the ACLs of directories that house information they want to share with other members of the group.

  If you place a group owned by someone else on your ACLs, the group's owner can change the group's membership without informing you. Someone new can gain or lose access in a way you did not intend and without your knowledge.

  shared use of group
  groups shared use

- Group use: you create a group and then use the pts chown command to assign ownership to a group--either another group or the group itself (the latter type is a self-owned group). You inform the members of the owning group that they all can administer the owned group. For instructions for the pts chown command, see To Change a Group's Owner.

  group use of group
  self-owned group
  groups group use
  groups group-owned groups
  groups self-owned groups

  The main advantage of designating a group as an owner is that several people share responsibility for administering the group. A single person does not have to perform all administrative tasks, and if the group's original owner leaves the cell, there are still other people who can administer it.

  However, everyone in the owner group can make changes that affect others negatively: adding or removing people from the group inappropriately or changing the group's ownership to themselves exclusively. These problems can be particularly sensitive in a self-owned group. Using an owner group works best if all the members know and trust each other; it is probably wise to keep the number of people in an owner group small.

### Group Names

The groups you create must have names with two parts, in the following format:

owner_name: group_name

The owner_name prefix indicates which user or group owns the group (naming rules appear in To Create a Group). The group_name part indicates the group's purpose or its members' common interest. Group names must always be typed in full, so a short group_name is most practical. However, names like terry:1 and terry:2 that do not indicate the group's purpose are less useful than names like terry:project.

Groups that do not have the owner_name prefix possibly appear on some ACLs; they are created by system administrators only. All of the groups you create must have an owner_name prefix.

groups naming conventions

### Group-creation Quota

By default, you can create 20 groups, but your system administrators can change your group-creation quota if appropriate. When you create a group, your group quota decrements by one. When a group that you created is deleted, your quota increments by one, even if you are no longer the owner. You cannot increase your quota by transferring ownership of a group to someone else, because you are always recorded as the creator.

If you exhaust your group-creation quota and need to create more groups, ask your system administrator. For instructions for displaying your group-creation quota, see To Display A Group Entry.

group-creation quota defined
groups creation quota

## Displaying Group Information

You can use the following commands to display information about groups and the users who belong to them:

- To display the members of a group, or the groups to which a user belongs, use the pts membership command.

- To display the groups that a user or group owns, use the pts listowned command.

- To display general information about a user or group, including its name, AFS ID, creator, and owner, use the pts examine command.

The system:anyuser and system:authuser system groups do not appear in a user's list of group memberships, and the pts membership command does not display their members. For more information on the system groups, see Using the System Groups on ACLs.

### To Display Group Membership

Issue the pts membership command to display the members of a group, or the groups to which a user belongs.

       % pts membership <user or group name or id>+

where user or group name or id specifies the name or AFS UID of each user for which to display group membership, or the name or AFS GID of each group for which to display the members. If identifying a group by its AFS GID, precede the GID with a hyphen (-) to indicate that it is a negative number.

commands pts membership
pts commands membership

### Example: Displaying the Members of a Group

The following example displays the members of the group terry:team.

       % pts membership terry:team
       Members of terry:team (id: -286) are:
         terry
         smith
         pat
         johnson

examples displaying members of a group

### Example: Displaying the Groups to Which a User Belongs

The following example displays the groups to which users terry and pat belong.

       % pts membership terry pat
       Groups terry (id: 1022) is a member of:
         smith:friends
         pat:accounting
         terry:team
       Groups pat (id: 1845) is a member of:
         pat:accounting
         sam:managers
         terry:team

### To Display the Groups a User or Group Owns

Issue the pts listowned command to display the groups that a user or group owns.

       %  pts listowned <user or group name or id>+

where user or group name or id specifies the name or AFS UID of each user, or the name or AFS GID of each group, for which to display group ownership. If identifying a group by its AFS GID, precede the GID with a hyphen (-) to indicate that it is a negative number.

displaying groups owned by a group
commands pts listowned
users listing groups owned
groups listing groups owned
pts commands listowned

### Example: Displaying the Groups a Group Owns

The following example displays the groups that the group terry:team owns.

       % pts listowned -286
       Groups owned by terry:team (id: -286) are:
         terry:project
         terry:planners

examples displaying groups a group owns

### Example: Displaying the Groups a User Owns

The following example displays the groups that user pat owns.

       % pts listowned pat
       Groups owned by pat (id: 1845) are:
          pat:accounting
          pat:plans

examples displaying groups a user owns

### To Display A Group Entry

Issue the pts examine command to display general information about a user or group, including its name, AFS ID, creator, and owner.

       %  pts examine <user or group name or id>+

where user or group name or id specifies the name or AFS UID of each user, or the name or AFS GID of each group, for which to display group-related information. If identifying a group by its AFS GID, precede the GID with a hyphen (-) to indicate that it is a negative number.

The output includes information in the following fields:

`Name`

  For users, this is the character string typed when logging in. For machines, the name is the IP address; a zero in address field acts as a wildcard, matching any value. For most groups, this is a name of the form owner_name: group_name. Some groups created by your system administrator do not have the owner_name prefix. See Group Names.

`id`

  This is a unique identification number that the AFS server processes use internally. It is similar in function to a UNIX UID, but operates in AFS rather than the UNIX file system. Users and machines have positive integer AFS user IDs (UIDs), and groups have negative integer AFS group IDs (GIDs).

  AFS UIDs and GIDs
  GID, AFS
  UID, AFS
`owner`

  This is the user or group that owns the entry and so can administer it.

`creator`

  The name of the user who issued the pts createuser and pts creategroup command to create the entry. This field is useful mainly as an audit trail and cannot be changed.

`membership`

  For users and machines, this indicates how many groups the user or machine belongs to. For groups, it indicates how many members belong to the group. This number cannot be set explicitly.

`flags`

  This field indicates who is allowed to list certain information about the entry or change it in certain ways. See Protecting Group-Related Information.

`group quota`

  This field indicates how many more groups a user is allowed to create. It is set to 20 when a user entry is created. The creation quota for machines or groups is meaningless because it not possible to authenticate as a machine or group.

commands pts examine
pts commands examine
displaying group owner
displaying group creator
displaying group-creation quota
groups owner, displaying
groups creator, displaying
users displaying number of group memberships
group-creation quota displaying

### Example: Listing Information about a Group

The following example displays information about the group pat:accounting, which includes members of the department that pat manages. Notice that the group is self-owned, which means that all of its members can administer it.

       % pts examine pat:accounting
       Name: pat:accounting, id: -673, owner: pat:accounting, creator: pat,
         membership: 15, flags: S-M--, group quota: 0

examples displaying information about group

### Example: Listing Group Information about a User

The following example displays group-related information about user pat. The two most interesting fields are `membership`, which shows that pat belongs to 12 groups, and `group quota`, which shows that pat can create another 17 groups.

      % pts examine pat
       Name: pat, id: 1045, owner: system:administrators, creator: admin,
         membership: 12, flags: S-M--, group quota: 17

examples displaying group information about a user
displaying group information
groups displaying information
users displaying group information

## Creating Groups and Adding Members

Use the pts creategroup command to create a group and the pts adduser command to add members to it. Users and machines can belong to groups, but other groups cannot.

When you create a group, you normally become its owner automatically. This means you alone can administer it: add and remove members, change the group's name, transfer ownership of the group, or delete the group entirely. If you wish, you can designate another owner when you create the group, by including the -owner argument to the pts creategroup command. If you assign ownership to another group, the owning group must already exist and have at least one member. You can also change a group's ownership after creating it by using the pts chown command as described in Changing a Group's Owner or Name.

### To Create a Group

Issue the pts creategroup command to create a group. Your group-creation quota decrements by one for each group.

       % pts creategroup -name <group name>+ [-owner <owner of the group>]

where

cg

  Is an alias for creategroup (and createg is the shortest acceptable abbreviation).

-name

  Names each group to create. The name must have the following format:

  owner_name: group_name

  The owner_name prefix must accurately indicate the group's owner. By default, you are recorded as the owner, and the owner_name must be your AFS username. You can include the -owner argument to designate another AFS user or group as the owner, as long as you provide the required value in the owner_name field:

  groups rules for assigning ownership
  rules for assigning group names

  - If the owner is a user, it must be the AFS username.

  - If the owner is another regular group, it must match the owning group's owner_name field. For example, if the owner is the group terry:associates, the owner field must be terry.

  - If the owner is a group without an owner_name prefix, it must be the owning group's name.

  The name can include up to 63 characters including the colon. Use numbers and lowercase letters, but no spaces or punctuation characters other than the colon.

-owner

  Is optional and assigns ownership to a user other than yourself, or to a group. If you specify a group, it must already exist and have at least one member. (This means that to make a group self-owned, you must issue the pts chown command after using this command to create the group, and the pts adduser command to add a member. See Changing a Group's Owner or Name.)

  Do not name a machine as the owner. Because no one can authenticate as a machine, there is no way to administer a group owned by a machine.

commands pts creategroup
pts commands creategroup

### Example: Creating a Group

examples creating a group

In the following example user terry creates a group to include all the other users in his work team, and then examines the new group entry.

       % pts creategroup terry:team
       group terry:team has id -286
       % pts examine terry:team
       Name: terry:team, id: -286, owner: terry, creator: terry,
         membership: 0, flags: S----, group quota: 0.

### To Add Members to a Group

Issue the pts adduser command to add one or more users to one or more groups. You can always add members to a group you own (either directly or because you belong to the owning group). If you belong to a group, you can add members if its fourth privacy flag is the lowercase letter a; see Protecting Group-Related Information.

       % pts adduser -user <user name>+ -group <group name>+

You must add yourself to groups that you own, if that is appropriate. You do not belong automatically just because you own the group.

If you already have a token when you are added to a group, you must issue the klog command to reauthenticate before you can exercise the permissions granted to the group on ACLs.

where

-user

  Specifies the username of each user to add to the groups named by the -group argument. Groups cannot belong to other groups.

-group

  Names each group to which to add users.

groups adding members
commands pts adduser
pts commands adduser
users adding as group members

### Example: Adding Members to a Group

In this example, user terry adds himself, pat, indira, and smith to the group he just created, terry:team, and then verifies the new list of members.

       % pts adduser -user terry pat indira smith -group terry:team
       % pts members terry:team
       Members of terry:team (id: -286) are:
         terry
         pat
         indira
         smith

examples adding members to a group
adding users to groups
creating groups
groups creating
groups adding members
groups owner as administrator

## Removing Users from a Group and Deleting a Group

You can use the following commands to remove groups and their members:

- To remove a user from a group, use the pts removeuser command

- To delete a group entirely, use the pts delete command

- To remove deleted groups from ACLs, use the fs cleanacl command

When a group that you created is deleted, your group-creation quota increments by one, even if you no longer own the group.

When a group or user is deleted, its AFS ID appears on ACLs in place of its AFS name. You can use the fs cleanacl command to remove these obsolete entries from ACLs on which you have the a (administer) permission.

### To Remove Members from a Group

Issue the pts removeuser command to remove one or more members from one or more groups. You can always remove members from a group that you own (either directly or because you belong to the owning group). If you belong to a group, you can remove members if its fifth privacy flag is the lowercase letter r; see Protecting Group-Related Information. (To display a group's owner, use the pts examine command as described in To Display A Group Entry.)

       % pts removeuser -user  <user name>+  -group <group name>+

where

-user

  Specifies the username of each user to remove from the groups named by the -group argument.

-group

  Names each group from which to remove users.

commands pts removeuser
pts commands removeuser

### Example: Removing Group Members

The following example removes user pat from both the terry:team and terry:friends groups.

       % pts removeuser  pat -group terry:team terry:friends

examples removing group members

### To Delete a Group

Issue the pts delete command to delete a group. You can always delete a group that you own (either directly or because you belong to the owning group). To display a group's owner, use the pts examine command as described in To Display A Group Entry.

       % pts delete <user or group name or id>+

where user or group name or id specifies the name or AFS UID of each user, or the name or AFS GID of each group, to delete. If identifying a group by its AFS GID, precede the GID with a hyphen (-) to indicate that it is a negative number.

commands pts delete
pts commands delete

### Example: Deleting a Group

examples deleting a group

In the following example, the group terry:team is deleted.

       % pts delete terry:team

### To Remove Obsolete ACL Entries

Issue the fs cleanacl command to remove obsolete entries from ACLs after the corresponding user or group has been deleted.

       % fs cleanacl [<dir/file path>+]

where dir/file path name each directory for which to clean the ACL. If you omit this argument, the current working directory's ACL is cleaned.

examples removing deleted groups from ACLs
commands fs cleanacl
fs commands cleanacl

### Example: Removing an Obsolete ACL Entry

After the group terry:team is deleted, its AFS GID (-286) appears on ACLs instead of its name. In this example, user terry cleans it from the ACL on the plans directory in his home directory.

       % fs listacl plans
       Access list for plans is
       Normal rights:
         terry rlidwka
         -268 rlidwk
         sam rliw
       % fs cleanacl plans
       % fs listacl plans
       Access list for plans is
       Normal rights:
         terry rlidwka
         sam rliw

groups removing members
groups deleting
removing users from groups
deleting groups
removing users from groups
users removing from groups
removing obsolete ACL entries
ACL removing obsolete entries

## Changing a Group's Owner or Name

To change a group's owner, use the pts chown command. To change its name, use the pts rename command.

You can change the owner or name of a group that you own (either directly or because you belong to the owning group). You can assign group ownership to another user, another group, or the group itself. If you are not already a member of the group and need to be, use the pts adduser command before transferring ownership, following the instructions in To Add Members to a Group.

The pts chown command automatically changes a group's owner_name prefix to indicate the new owner. If the new owner is a group, only its owner_name prefix is used, not its entire name. However, the change in owner_name prefix command does not propagate to any groups owned by the group whose owner is changing. If you want their owner_name prefixes to indicate the correct owner, you must use the pts rename command.

Otherwise, you normally use the pts rename command to change only the group_name part of a group name (the part that follows the colon). You can change the owner_name prefix only to reflect the actual owner.

### To Change a Group's Owner

Issue the pts chown command to change a group's name.

       % pts chown  <group name> <new owner>

where

group name

  Specifies the current name of the group to which to assign a new owner.

new owner

  Names the user or group that is to own the group.

commands pts chown
pts commands chown

### Example: Changing a Group's Owner to Another User

In the following example, user pat transfers ownership of the group pat:staff to user terry. Its name changes automatically to terry:staff, as confirmed by the pts examine command.

       % pts chown pat:staff terry
       % pts examine terry:staff
       Name: terry:staff, id: -534, owner: terry, creator: pat,
         membership: 15, flags: SOm--, group quota: 0.

examples changing group owner

### Example: Changing a Group's Owner to Itself

In the following example, user terry makes the terry:team group a self-owned group. Its name does not change because its owner_name prefix is already terry.

       % pts chown terry:team terry:team
       % pts examine terry:team
       Name: terry:team, id: -286, owner: terry:team, creator: terry,
         membership: 6, flags: SOm--, group quota: 0.

examples creating a self-owned group

### Example: Changing a Group's Owner to a Group

In this example, user sam transfers ownership of the group sam:project to the group smith:cpa. Its name changes automatically to smith:project, because smith is the owner_name prefix of the group that now owns it. The pts examine command displays the group's status before and after the change.

       % pts examine sam:project
       Name: sam:project, id: -522, owner: sam, creator: sam,
         membership: 33, flags: SOm--, group quota: 0.
       % pts chown sam:project smith:cpa
       % pts examine smith:project
       Name: smith:project, id: -522, owner: smith:cpa, creator: sam,
         membership: 33, flags: SOm--, group quota: 0.

### To Change a Group's Name

Issue the pts rename command to change a group's name.

       % pts rename  <old name> <new name>

where

old name

  Specifies the group's current name.

new name

  Specifies the complete new name to assign to the group. The owner_name prefix must correctly indicate the group's owner.

commands pts rename
pts commands rename

### Example: Changing a Group's group_name Suffix

The following example changes the name of the smith:project group to smith:fiscal-closing. The group's owner_name prefix remains smith because its owner is not changing.

       % pts examine smith:project
       Name: smith:project, id: -522, owner: smith:cpa, creator: sam,
         membership: 33, flags: SOm--, group quota: 0.
       % pts rename smith:project smith:fiscal-closing
       % pts examine smith:fiscal-closing
       Name: smith:fiscal-closing, id: -522, owner: smith:cpa, creator: sam,
         membership: 33, flags: SOm--, group quota: 0.

examples changing group name

### Example: Changing a Group's owner_name Prefix

In a previous example, user pat transferred ownership of the group pat:staff to user terry. Its name changed automatically to terry:staff. However, a group that terry:staff owns is still called pat:plans, because the change to a group's owner_name that results from the pts chown command does not propagate to any groups it owns. In this example, a member of terry:staff uses the pts rename command to change the name to terry:plans to reflect its actual ownership.

       % pts examine pat:plans
       Name: pat:plans, id: -535, owner: terry:staff, creator: pat,
         membership: 8, flags: SOm--, group quota: 0.
       % pts rename pat:plans terry:plans
       % pts examine terry:plans
       Name: terry:plans, id: -535, owner: terry:staff, creator: pat,
         membership: 8, flags: SOm--, group quota: 0.

groups changing name
changing group owner
changing group name
groups changing owner

## Protecting Group-Related Information

A group's privacy flags control who can administer it in various ways. The privacy flags appear in the `flags` field of the output from the pts examine command command; see To Display A Group Entry. To set the privacy flags for a group you own, use the pts setfields command as instructed in To Set a Group's Privacy Flags.

### Interpreting the Privacy Flags

The five privacy flags always appear, and always must be set, in the following order:

s

  Controls who can issue the pts examine command to display the entry.

o

  Controls who can issue the pts listowned command to list the groups that a user or group owns.

m

  Controls who can issue the pts membership command to list the groups a user or machine belongs to, or which users or machines belong to a group.

a

  Controls who can issue the pts adduser command to add a user or machine to a group.

r

  Controls who can issue the pts removeuser command to remove a user or machine from a group.

Each flag can take three possible types of values to enable a different set of users to issue the corresponding command:

- A hyphen (-) means that the group's owner can issue the command, along with the administrators who belong to the system:administrators group.

- The lowercase version of the letter means that members of the group can issue the command, along with the users indicated by the hyphen.

- The uppercase version of the letter means that anyone can issue the command.

For example, the flags `SOmar` on a group entry indicate that anyone can examine the group's entry and list the groups that it owns, and that only the group's members can list, add, or remove its members.

The default privacy flags for groups are `S-M--`, meaning that anyone can display the entry and list the members of the group, but only the group's owner and members of the system:administrators group can perform other functions.

### To Set a Group's Privacy Flags

Issue the pts setfields command to set the privacy flags on one or more groups.

       % pts setfields -nameorid <user or group name or id>+
                       -access <set privacy flags>

where

-nameorid

  Specifies the name or AFS GID of each group for which to set the privacy flags. If identifying a group by its AFS GID, precede the GID with a hyphen (-) to indicate that it is a negative number.

-access

  Specifies the privacy flags to set for each group. Observe the following rules:

  - Provide a value for all five flags in the order somar.

  - Set the first flag to lowercase s or uppercase S only.

  - Set the second flag to the hyphen (-) or uppercase O only. For groups, AFS interprets the hyphen as equivalent to lowercase o (that is, members of a group can always list the groups that it owns).

  - Set the third flag to the hyphen (-), lowercase m, or uppercase M.

  - Set the fourth flag to the hyphen (-), lowercase a, or uppercase A. The uppercase A is not a secure choice, because it permits anyone to add members to the group.

  - Set the fifth flag to the hyphen (-) or lowercase r only.

commands pts setfields
pts commands setfields

### Example: Setting a Group's Privacy Flags

The following example sets the privacy flags on the terry:team group to set the indicated pattern of administrative privilege.

       % pts setfields terry:team -access SOm--

- Everyone can issue the pts examine command to display general information about it (uppercase S).

- Everyone can issue the pts listowned command to display the groups it owns (uppercase O).

- The members of the group can issue the pts membership command to display the group's members (lowercase m).

- Only the group's owner, user terry, can issue the pts adduser command to add members (the hyphen).

- Only the group's owner, user terry, can issue the pts removeuser command to remove members (the hyphen).

examples setting group's privacy flags
protection group-related information
groups privacy flags
privacy flags on groups
s privacy flag on groups
o privacy flag on groups
m privacy flag on groups
a privacy flag on groups
r privacy flag on groups