Guide to AFS and ACLs

  1. Brief User's guide

    1. aklog command
    2. tokens command
    3. kpasswd command
    4. fs command
    5. Cache flushing
    6. pts command
    7. unlog command
  2. Groups

    1. Group Names
    2. Creating groups and adding members
    3. Removing Users from a group and deleting a group
    4. Listing members of group
    5. Changing a group's owner or name
  3. Access Control Lists (ACL)

    1. Listing an ACL
    2. Setting/Changing an ACL
  4. AFS organization in STAR

  5. RCF AFS service

  6. More information

1. Brief User's guide

First, be sure your environment is set up correctly. This will ensure the AFS commands (normally resident in /usr/afsws/bin, /usr/afsws/etc) are on your path.

1.1 aklog command:

cd to /afs and you will see the rhic directory. If your machine doesn't have an /afs directory, then it isn't an AFS client. If you're a RHIC user, the AFS cell is "Kerberized" that is, AFS tokens are granted through Kerberos/K5 authentication. Right after you login, check if you have a Kerberos ticket by typing the command
% klist
If this command shows lines like
Ticket cache: FILE:/tmp/krb5cc_5650
Default principal: xxx@RHIC.BNL.GOV

Valid starting     Expires            Service principal
10/13/14 14:55:56  10/18/14 14:55:53  krbtgt/RHIC.BNL.GOV@RHIC.BNL.GOV
10/13/14 14:56:01  10/18/14 14:55:53  afs@RHIC.BNL.GOV
then you have Kerberos credentials and can proceed to execute
 % aklog 
to get an AFS token. If the lines shows instead
klist: No credentials cache found (ticket cache FILE:/tmp/krb5cc_5650)
your session does not have any Kerberos credentials and you will need to use instead
% kinit
{enter your Kerberos password at the prompt}
% aklog

1.2 tokens command:

To check if you get your token, issue tokens command:
% tokens

1.3 kpasswd command:

To change your AFS password, issue kpasswd command:
% kpasswd 

1.4 fs command:

This is the most often used command. To get help, you can run 'man fs' or 'fs help' To list a directory's (ACLs):
 % fs la directory 
To set directories' ACLs:
 % fs sa -dir directories -acl ACLentry 
Each ACLentry has two parts: a user or group name and the access control rights, separated by a space (for example, star rlidw). Type a combination of the seven letters representing the rights, or one of the four shorthand words.

Access Control Rights:
    r: read l: lookup i: insert d: delete w: write k: lock

Shorthand Notation:
    write = rlidwk read = rl all = rlidwka none = removes entry

1.4a Cache flushing:

The command
% fs flushvolume -path path 
will trigger an AFS cache flush for the AFS volume that includes the specified file. Using 'flush' rather than 'flushvolume' will flush the file only. Sometimes when using AFS to access remote disks this can be necessary to avoid getting outdated material (I don't know why AFS fails to take care of updating itself).

1.5 Pts command:

List members of a group:
    pts mem group
List groups a user belongs to:
    pts mem user

1.6 Unlog command:

To destroy your token, issue unlog command:
    unlog cell name
If you don't unlog, your token is still alive even when you logout.

For more information:

2. Groups

An AFS group is a defined list of individual users that you can place on the access control lists (ACLs) so that you can grant the same access rights to a number of people at once. When you create a group, you automatically become its owner. A group's owner is the only one allowed to administer the group. Administering a group includes adding members to it, removing members from it, renaming it, changing its owner, or deleting it entirely.

2.1 Group Names:

Most group names have two parts, separated by a colon, as follows: owner-name:group-name, for example, starlib:sl_sys is created by starlib. The owner-name is the name of the owner of the group; the group-name is the actual name of the group. You may also encounter groups that do not have an owner prefix; these are special groups created by system administrators. For example, star and phenix are special groups. AFS defines three system groups that you can put on your ACLs.
  • system:anyuser - This group includes everybody.
  • system:authuser - This group includes anyone who is currently authenticated in your cell.
  • sytem:administrators - Only few people in this group who administer your cell.

2.2 Creating groups and adding members:

Use the pts creategroup command to create a group:
pts creategroup -name <group name> -c rhic
(You have to specify the cell, rhic, if your default cell is different)
Use the pts adduser command to add user(s) to a group:
pts adduser -user <user name> -group <group name>
pts creategroup -name olson:sl_txm
pts adduser -user love toan irmscher jacobs tull -group olson:sl_txm

2.3 Removing Users from a group and deleting a group

Use the pts removeuser command to remove a user from a group
pts removeuser -user <user name> -group <group name>
pts removeuser -user jacobs -group bloomer:sl_txm
Use the pts delete command to delete a group entirely:
pts delete <group name> -c rhic
(You have to specify the cell, rhic, if your default cell is different)
pts delete bloomer:sl_txm
Note: After deleting group, you should run fs cleanacl command to remove deleted group(s) from ACLs.
After Olson removed the group olson:sl_txm, the group still appears on directory /afs/rhic/star/users/olson. To remove the group from the ACL of this directory:
fs cleanacl /afs/rhic/star/users/olson

2.4 Listing members of group

Use the pts mem command to display group's members.
pts mem <group name>
pts mem star
pts mem -group star phenix

2.5 Changing a group's owner or name

Use the pts chown command to change the owner of a command.
pts chown -name <group name> -owner <new owner>
Because Bloomer left, he wants to change the ownership to Olson:
pts chown -name bloomer:sl_txm -owner olson
Use the pts rename command to change the group's name:
pts rename <old name> <new name>
Olson wants to change olson:sl_txm to olson:sl_foo
pts rename olson:sl_txm olson:sl_foo

3. Access Control Lists (ACL)

Every directory has its own access control list (ACL) that is used to define which users or groups can access the directory and its files. Defining access at the directory level has several consequences: Files inherit the access rights associated with their parent directory. If you move a file to a new directory, the file gets the access rights of its new directory. When you create a subdirectory, it inherits the current access rights of its parents directory. You can then set the subdirectory's ACL to be different from its parents. There are 7 standard access rights available on ACLs:
  • The LOOKUP (l) right allows the possessor to issue ls
  • The INSERT (i) right allows the possessor to create new files or directories.
  • The DELETE (d) right allows the possessor to remove files or direcotries.
  • The ADMIN (a) right allows the possessor to change the ACL for the directories
  • The READ (r) right allows the possessor to read the contents of the files.
  • The WRITE (w) right allows the possessor to modify the contents of the files.
  • The LOCK (k) right allows the possessor to run programs that need to place advisory locks on files in the directory (don't worry about this right)

3.1 Listing an ACL

The fs listacl command is used to view a directory's ACL.
fs la < dir path >
fs la /afs/rhic/star
fs la
fs la *

3.2 Setting/Changing an ACL

You are allowed to change any ACL for which you have the ADMIN right. Use the fs sa command to set/change the ACL.
fs sa -dir < dir > -acl < users/groups > [rliwadk]
fs sa -dir /afs/rhic/star -acl star all phenix rl system:anyuser none
Here, star group has all 7 rights, but phenix group only has read and lookup, and sytem:anyuser (the world) doesn't have any rights at all.


4. AFS organization in STAR

The STAR AFS area is at /afs/rhic/star. The web area is at /STARAFS. This area includes the STAR software library in both supported release versions (dev, new, pro, frozen, old), and the actual CVS-managed code repository. The AFS-STAR disk area contains all the STAR-specific system software, user codes for simulations and analysis, documentation files, compiled architecture dependent object files and libraries, linked executables, infrastructure scripts and binaries and much more.

AFS is particularly convenient for STAR computing at non-RCF sites. Under AFS, the offsite user is presented with the identical STAR AFS directory tree hierarchy and files. Because of the remote access capability, AFS requires additional security measures beyond the fairly lax procedures associated with the standard UNIX access restrictions. Under AFS, access to the managed directories and files is restricted via ACLs to users who are members of specific AFS groups. A given AFS directory may have different levels of access privileges and restrictions for one or more AFS groups. These groups are comprised of STAR AFS users who have need to access the particular library directories. ACL info is above.

4.1 STAR AFS Directory Hierarchy (Not an exhaustive list)

The following list includes the more relevant subdirectories under /afs/rhic/star for most user needs. Some directories are mostly obsolete (eg. login, starlib).


     /packages/repository - 
                     CVS Repository for STAR software.  Includes source
                     codes, idl files, kumacs, etc. but not the
                     compiled binaries and executables.

     /packages/SL* - Built software releases including sources,
                       libraries, executables

     /packages/dev, /new, /pro, /frozen, /old
                   - Official release versions; generally links to SL*

     /bin          - SOFI tools (binary executables)

     /doc/www      - Web documentation files

     /group        - Setup and login scripts (based on HEPiX system)


5. RCF AFS service

The RHIC Computing Facility (RCF) provides STAR with our AFS service. Their AFS page, linked below, provides information on obtaining AFS accounts, general information on the service, information on remote installation, etc.


6. More information

Based on Tom Nguyen's original of March 1996.