AFS groups

About

With the pts (protection server) command, you can create your own AFS groups and add them to AFS access control lists. AFS groups make it much easier to manage ACLs for large directory trees, and allow the addition of large numbers of users to an ACL with a single command. A typical use of AFS groups would be to create a new AFS directory that will be the root of a larger tree, and add the appropriate group to its ACL. Since a new AFS directory inherits its parent's ACL, sub-directories created in that tree will also have that group on their ACL. Adding or revoking a user's group membership will thus change access for that user throughout the entire directory tree.

System and special groups

In addition to user-created groups, the following system and special groups exist and have the listed membership:

system:anyuser
Anyone, anywhere.

system:authuser
Anyone authenticated to the ir.stanford.edu AFS cell (people with valid AFS accounts).

system:administrators
Authorized AFS administrators (Facilities staff).

The above special groups may be added to ACLs in the same way as user-created AFS groups.  There are a few more system:groups, but none that should concern you.  There also are some special groups with a dot in their name, such as:   username.cgi   or   username.cron

How to create and manage AFS groups

Note: typing  pts help  will list the various pts commands. Most pts commands can be used with or without named arguments.  For example,

   pts creategroup usrid:yourgroup
and
   pts creategroup -name usrid:yourgroup
will do the same thing.  Throughout the remaining examples, "usrid" is used as the username of the owner.  At Stanford, the "usrid" is typically the user's "sunetid".

Creating groups

AFS group names have the form username:<identifier>, and are created with the  pts creategroup  command.   The username specified will be the owner of the group, and must be a valid AFS user name (you will usually want to use your own AFS username).     For example, the command:

   pts creategroup usrid:yourgroup
would create a group called usrid:yourgroup.

Adding and removing users

To add a user to a group, use the  pts adduser  command:
   pts adduser jsmith usrid:yourgroup
To remove a user from a group, use the  pts removeuser  command:
   pts removeuser jsmith usrid:yourgroup

Listing your group names

To see a list of the groups you own, use the  pts listowned  command:
   pts listowned -name usrid

Listing group members

To see a list of the members of a group, use the  pts membership  command:
   pts membership usrid:yourgroup

Examining and changing group privacy flags

You can use the  pts examine  command to find out information about a group (you can also use this command on a AFS username).   For example, the command:

   pts examine usrid:yourgroup
would produce something similar to the following output:
Name: usrid:yourgroup, id: -3745, owner: usrid, creator:  usrid,
membership: 2, flags: S-M--, group quota: 0.
The above fields have the following meanings:
Name
The name of the group.
id
A unique identification number for the group.
owner
The owner of the group.
creator
The person who originally created the group.
membership
How many members belong to the group.
flags
Group privacy flags that determine who can list group properties or make certain changes to the group. See below for details.
group quota
How many more groups a user is allowed to create.

The five group privacy flags appear in the following order:

  1. Status (s): Controls who can use  pts examine  to list status information about a group.
  2. Owned (o): Controls who can use  pts listowned  to list groups owned by a group or user.
  3. Membership (m): Controls who can use  pts membership  to list groups a user belongs to, or users that belong to a group.
  4. Add (a): Controls who can use  pts adduser  to add a user to a group.
  5. Remove (r): Controls who can use  pts removeuser  to remove a user from a group.
Each one of the flags, somar, has three possible values: The default values of S-M-- gives anyone the ability to examine a group and see who belongs to a group, and only gives the owner of the group the other rights.  You can use the  pts setfields  command to change these default values.  Type  pts help setfields  for details about the syntax of this command.

Additional information

These off-site links will open in a new browser window.

OpenAFS documentation on groups

You can view the access restrictions for any directory with the following command:

   fs la -p dirname
which would list all group:access permissions for the given dirname.  You can use a period for dirname meaning "the current directory".  You can also use a fully-qualified path-name.

You can apply your groups to your directories to allow specific access by members of that group to your directories.  For example:

   fs sa -d dir1 -a usrid:yourgroup rlwk
would give all the members of that group read/locate/write/lock access to your "dir1" directory.
You could have another group with different members, and do something like:
   fs sa -d dir1 -a usrid:friends rl
to give them just read/locate access.  The general syntax is:

   fs sa -d <directory>+ -a <access list entries>+ 

The first portion of an access list entry is the user or group name.
The access codes in the last portion of each access list entry have these meanings:

   a (administer)
       Change the entries on the ACL.

   d (delete)
       Remove files and subdirectories from the directory or move them
       to other directories.

   i (insert)
       Add files or subdirectories to the directory by copying, moving
       or creating.

   k (lock)
       Set read locks or write locks on the files in the directory.

   l (lookup)
       List the files and subdirectories in the directory, stat the
       directory itself, and issue the fs listacl command to examine
       the directory's ACL.

   r (read)
       Read the contents of files in the directory; issue the "ls -l"
       command to stat the elements in the directory.

   w (write)
       Modify the contents of files in the directory, and issue the
       UNIX chmod command to change their mode bits.

You can remove an access list entry by using the word "none" as the access code following the user or group name.

What follows is a summary of the pts commands:

pts adduser
       pts adduser -user <user name>+ -group <group name>+
       pts ad -u <user name>+ -g <group name>+
pts creategroup
       pts creategroup -name <group name>+
       pts cg -na <group name>+ [-o <owner of the group>]
pts delete
       pts delete -nameorid <user or group name>+
       pts d -na <user or group name>+
pts examine
       pts examine -nameorid <user or group name>+
       pts e -na <user or group name>+
pts listowned
       pts listowned -nameorid <user or group name>+
       pts listo -na <user or group name>+
pts membership
       pts membership -nameorid <user or group name>+
       pts m -na <user or group name>+
       pts groups -na <user or group name>+
       pts g -na <user or group name>+
pts removeuser
       pts removeuser -user <user name>+ -group <group name>+
       pts rem -u <user name>+ -g <group name>+
pts setfields
       pts setfields -nameorid <user or group name>+
           [-access <set privacy flags>]
           [-groupquota <set limit on group creation>]
       pts setf -na <user or group name>+
           [-a <set privacy flags>]
           [-groupquota <set limit on group creation>]

       Example:  pts setf -na guertin:spires -a SOM--

"<list>+" represents a single entity  or  multiple-entity space-delimited list.