UNIX at Fermilab main page | Computing Division | Fermilab at Work | Fermilab Home
Fermilab CD logo Fermilab Computing Division
UNIX at Fermilab, Pre-Release 4.0

Chapter 9: The AFS File System

Fermilab is using the AFS (Andrew File System) as a distributed file service model, and it is installed on several machines on site in a production environment, including the FNALU cluster. This chapter discusses the basic concepts of AFS and provides information on the commands used to manage your files and directories in the AFS environment.

IBM Transarc®, the vendor for AFS, maintains a user's guide, a system administrator's guide and other documentation online at http://www.transarc.ibm.com/Library/documentation/afs_doc.html (refer to version 3.5). More information is available at http://www.fnal.gov/docs/afs/afs.html (under The UNIX Operating System from the UNIX Resources page).

9.1 Introduction to AFS

9.2 How to Determine if AFS is Installed on your System

9.3 Issues Related to Login and File Access

9.3.1 Authentication in AFS

9.3.2 Kerberos (AFS) Password

9.3.3 Standard UNIX Password on an AFS System

9.3.4 Managing your Token

9.4 AFS File System Commands

9.5 AFS Volumes and Quota

9.6 File and Directory Permissions

9.6.1 File Permissions

9.6.2 Directory Permissions via Access Control Lists (ACLs)

9.7 AFS Protection Groups

9.7.1 Permissions for Performing Group-Related Tasks

9.7.2 Listing Information about Groups

9.7.3 Modifying Group Characteristics

9.8 Implications of ACLs

9.8.1 Protecting your Subdirectories

9.8.2 AFS in Translator Mode

9.9 File Locking in AFS

9.10 Frequently Asked Questions

9.10.1 Lost Access to Files

9.10.2 AFS and the UNIX Command "find"

9.10.3 Error Messages

9.10.4 Retrieving Old Files

9.10.5 Link Failure

9.1 Introduction to AFS

AFS is a modern implementation of distributed file serving. AFS has several advantages over older file systems such as NFS, particularly in the areas of:

All systems participating in the AFS file system have the same view of the file system. All files for a set of machines known as a cell exist under /afs/<cellname>. The cellname for Fermilab is fnal.gov, thus all files that are part of the AFS file system are located under /afs/fnal.gov. There is also a symbolic link to a shorthand version of the cell name, which is simply /afs/fnal. Other cells are also accessible. They are listed as directories under /afs, e.g., the CERN cell at /afs/cern.ch.

9.2 How to Determine if AFS is Installed on your System

To find out if AFS is installed, issue the command: 

% ps -ef | grep afsd

If you get output of the form (note the /usr/vice/etc/afsd): 

root   305     1  0   Sep 30 ?       14:10 /usr/vice/etc/afsd -stat 2800 -dcache 2400 -daemons 5 -volumes 128 
root   306     1  0   Sep 30 ?        5:47 /usr/vice/etc/afsd -stat 2800 -dcache 2400 -daemons 5 -volumes 128

then it is installed and running on your machine. If you do not get output lines like this, AFS is not installed. However it is still possible that you have access to the AFS file system via a translator1 service. We discuss translator mode in section 9.8.2 AFS in Translator Mode. To check, enter the command: 

% df |grep afs

If no output is returned, AFS is not running on your machine in any capacity. If output is returned and the line begins with a node name preceding /afs, for example: 

nodename:/afs                  144000000           0   144000000     0%

then AFS is running in translator mode. (If the output line begins with /afs, then AFS is actually installed on your machine.)

9.3 Issues Related to Login and File Access

9.3.1 Authentication in AFS

On machines running AFS, as on most systems, providing a username and password is sufficient to identify a user as legitimate, and allow the login to succeed. However, to access AFS files, you must provide a password recognized by AFS, called a Kerberos password. This authenticates you to AFS. Once you are authenticated, AFS issues what is known as a Kerberos token to your login process. It is the token that allows you access to the AFS file system. As long as you remain logged on, the Kerberos token "lives" for a period of time set by the AFS administrator of the cell; in the Fermilab cell it is set to six days.

The token is passed to all subprocesses of the login process. All normal UNIX interactive operations are therefore automatically authenticated, and access is granted to files in the AFS tree, provided you have the appropriate permissions (AFS permissions are covered in section 9.6 File and Directory Permissions). The Fermilab standard batch interface fbatch provides for token renewal at job execution time, since you can't control when your batch jobs actually run.

Situations occasionally arise in which you are not automatically authenticated (e.g., some remote login methods) or you lose your token (e.g., you remain logged in for more than six days). When this happens and you need to obtain a new token, issue the command string: 

% pagsh  
% klog

pagsh starts a special AFS shell under your login process. klog prompts you for your AFS password and obtains a Kerberos token associated with this shell, thus granting authentication and access to files.

A few notes:

  1. Running pagsh first is much more secure than just running klog. It ensures that the token is associated with your pagsh process, and thus with all processes you spawn. klog by itself gets a token associated with your UID, which is not always unique. This could potentially allow another user to share the token, which is undesirable.
  2. You cannot enter the commands on one line in the format pagsh;klog. pagsh starts a new sh shell, and klog needs to be run at the new shell prompt on the next line.
  3. pagsh changes your shell to sh, so you will need to run your preferred shell afterwards (e.g., enter tcsh, bash, or ksh on the command line). You may also then want to source your .login and .cshrc or your .profile and .shrc scripts to ensure that your FUE environment is back to normal.

There are Kerberos authentication problems with running programs that spawn jobs external to your login process group. at and cron fall into this category. You can run the job, but it will not run with authentication, and most likely will not be able to write into /afs space. If you are using a machine on which the kerberos product is installed, use kcron (see http://www.fnal.gov/docs/strongauth/html/spectopics.html#42566). If not, a work-around is available for executing an authenticated cron job. Send a request to the help desk for the full details of this procedure (see http://csdserver1.fnal.gov/HelpDesk/cd/).

Be aware that being logged on as root grants you no special permissions in /afs file space; there is no such thing as being "authenticated as root".

9.3.2 Kerberos (AFS) Password

You will have a Kerberos password (sometimes called an AFS password), for any account on a system that uses the AFS file system, for example FNALU. The Kerberos password, which you enter at login time, allows two operations to proceed:

You can change your Kerberos password using the command: 

% kpasswd

The system will prompt you for the necessary information. This command changes your Kerberos password for all systems in the cell you are in.

We recommend that you limit your password to eight characters. This enforces consistent behavior in a multi-vendor AFS environment. On some platforms the login program may truncate a long password after eight characters, allowing login to proceed but denying access to the file system.

On strengthened UNIX systems running AFS, there are two kpasswd commands, one for AFS and one for Kerberos. Your $PATH should be set such that the Kerberos kpasswd comes first. Kerberos is implemented at Fermilab such that your AFS tokens will be obtained automatically. If you are unsure which kpasswd is being invoked, force the system to use the Kerberos version by running setup kerberos first. See http://www.fnal.gov/docs/strongauth/html/user.html#29244 for more information.

9.3.3 Standard UNIX Password on an AFS System

Depending on how the AFS file system was installed, you may or may not have a standard UNIX password in addition to your Kerberos password. In other words, you may have a standard UNIX password even if you never need to use it! On FNALU, AFS was installed so that you have only a Kerberos password; no standard UNIX password is defined.

You can find out if you have a standard UNIX password by attempting to change it via the standard UNIX command passwd. If the command does not succeed (assuming you provide the correct old password if requested), then you do not have a standard UNIX password. Note that the passwd command returns a different error message on each different UNIX flavor.

If you have both, at login you should provide the Kerberos password so that you obtain your Kerberos token. If instead you provide your standard UNIX password, the system will log you in, but you will not obtain a token and thus will not be able to access AFS files. If the passwords are the same, the Kerberos password automatically takes precedence.

Generally, the Kerberos password is the only password you need. There are exceptions; for example, remote login via a method that doesn't understand Kerberos passwords (e.g., MAC-X to some UNIX platforms). In this case, after logging in using a standard UNIX password, you would need to run the command string pagsh and klog as described in section 9.3.1 Authentication in AFS.

9.3.4 Managing your Token

View Active Tokens

To see what tokens you currently hold, you can issue the command: 

% tokens

The output should look similar to this: 

Tokens held by the Cache Manager: 
 
User's (AFS ID 6302) tokens for afs@fnal.gov [Expires Oct 21 10:22] 
User aheavey's tokens for krbtgt.FNAL.GOV@fnal.gov [Expires Oct 21 10:22] 
   --End of list--

If the output shows no tokens (or only the krbtgt token, the second one shown above), then you only have access to (usually a very limited number of) files designated as accessible to the special user system:anyuser (a pre-defined AFS protection group; see section 9.7 AFS Protection Groups). As its name implies, this designation includes anyone who can access the system (e.g., a user with a standard UNIX password but no Kerberos password).

Get Back an Expired Token

If you remain logged on beyond the set token expiration period, you will find that you no longer have access to AFS files. The system will likely return the message Permission denied when you attempt a file operation. To get back the token associated with your login process, issue the commands2: 

% pagsh 
% klog

If you are unexpectedly unable to edit your files, try this first! Expired tokens are often the reason for this problem. See the notes in section 9.3.1 Authentication in AFS regarding these commands.

Destroy a Token

Logging out does not destroy your token; it remains "live" for up to 26 hours afterwards. This is a security risk. Prior to logging out, we advise that you issue the command: 

% unlog

to destroy the token. If you create a .logout file, you should include this command in it.

Token Issues for Remote Login

One practical issue raised by the Kerberos environment involves the use of the Berkeley networking programs such as rlogin, rsh, and rcp. telnet automatically authenticates the user and avoids the issues discussed here.

If your machine has the Kerberos product installed on it, see the Strong Authentication at Fermilab Manual at http://www.fnal.gov/docs/strongauth/index.html

Normally systems are equivalenced to enable the use of the rlogin, rsh, and rcp protocols. The equivalencing of the machines implies that once you are logged into one system, you may log into the equivalenced machines without providing further proof of identity, such as a password. This doesn't fit in with the Kerberos authentication system.

On FNALU, token-passing is available for rsh and rcp.3 If you have authenticated into the /afs/fnal.gov cell, you can use rcp and rsh more or less normally between AFS machines; the token will be passed along with the request, and the network communications will be authenticated automatically.4

rlogin is more complicated. When equivalencing between two machines is enabled, the rlogin protocol does not ask for a password. rlogin works, but the remote user is not authenticated at login time, and cannot access most files.

We recommend that you use telnet rather than rlogin in order to avoid this problem.

If you need to use rlogin for some reason, immediately after login issue the commands: 

% pagsh 
% klog

as described in section 9.3.1 Authentication in AFS, to obtain authentication.

9.4 AFS File System Commands

AFS provides a command (with many options) that allows you to address file system issues such as checking permissions, checking quota, making mount points, finding where a volume is mounted in the file tree, and so on. The AFS file system (fs) command is entered in the format: 

% fs <main_option> <options> <arguments>

Many of the options can be abbreviated, and option flags can often be omitted from the command. To get a list of the main options of the fs command, enter: 

% fs help

Here is an edited output listing showing only a few of the options: 

fs: Commands are: 
listacl         list access control list 
listquota       list volume quota 
lsmount         list mount point 
quota           show volume quota usage 
rmmount         remove mount point 
setacl          set access control list 
setquota        set volume quota 
whereis         list file's location 
whichcell       list file's cell

To get usage information on a particular fs option, enter: 

% fs <option> -help

For example: 

% fs setacl -help 

Usage: fs setacl -dir <directory>+ -acl <access list entries>+ [-clear ] [-negat 
ive ] [-id ] [-if ] [-help ]

A complete command reference can be found at the IBM Transarc® site under http://www.transarc.ibm.com/Library/documentation/afs/3.5/unix/cmd/cmd.htm.

9.5 AFS Volumes and Quota

UNIX divides disks into partitions. AFS further divides partitions into subsections called volumes. A volume houses a subtree of related files and directories. Normally, volumes are considerably smaller than traditional file systems. For example, each user's home directory would normally be stored in a separate volume. Large sub-directories are further sub-divided. You do not need to know which file server houses any volume. AFS locates volumes automatically.

For information on disk areas in AFS space available to Fermilab users, see http://www.fnal.gov/cd/forms/afsdisk.html. To examine the quota on a volume within AFS, the fs listquota command may be used. You can request information on several directories at a time. For example the following command requests information on the current working directory (.) and on another one specified via the environment variable $UAFWWW: 

% fs listquota . $UAFWWW 

Volume Name            Quota    Used    % Used   Partition 
room.aheavey          130000  126024       97%<<       75%      <<WARNING 
files.reports.UNIX   2000000   77370        4%         63%

The output includes the name of the volume containing the specified directory(ies), the quota size, amount used, percent used, and the percent of space used on the partition containing the volume. You might also get a warning! All sizes are in kilobytes.

9.6 File and Directory Permissions

9.6.1 File Permissions

File permissions work quite differently from those in standard UNIX. In AFS, you can use the chmod command just as you would in a standard UNIX file system. However, it behaves differently. Although in AFS all the permission bits on a file may be examined or changed, only the owner bits are actually used in AFS, and they apply to all users of the file (as permitted by users' ACL settings; see below). To turn off write access to a particular file by all users, including the owner, you just need to turn off the owner write bit of the file.

9.6.2 Directory Permissions via Access Control Lists (ACLs)

All other AFS permissions are done with Access Control Lists (ACLs) which take effect at the directory level only. Every directory has its own ACL that defines who can access the directory and its files. Each entry in an ACL consists of a username or an AFS protection group paired with a set of permissions (e.g., read, write). An AFS protection group is simply a list of usernames grouped to share a set of permissions in one or more ACLs. If a user is in two or more ACL entries (e.g., is a member of two groups listed in the ACL) with different permissions assigned, the user gets the union of the permissions.

The permissions granted in a directory's ACL represent the maximum permissions. If a file in the directory has more restrictive permissions set, the user is limited by the restrictions on the file. If a file has more lenient permissions set, the user is limited by his ACL entry.

ACL rights include:

l
lookup rights (allows user to issue an ls command on files in the directory, examine the directory's ACL, and access the directory's subdirectories which are protected by their own ACLs)
i
insert rights (allows user to create new files or copy files into the directory)
d
delete rights (allows user to remove files or move them to other directories)
a
administrator rights (allows user to change the ACL for a directory; note that you always have this right for your home directory even if you accidentally remove this ACL.)
r
read rights (allows user to look at the directory's contents and to read the data in the files contained in the directory)
w
write rights (allows user to modify the contents of the files in the directory and to change the UNIX mode bits with the command chmod)
k
lock rights (allows user to run programs that need to flock files in this directory; see the man pages for flock)

Rights may also be referred to by special names that designate commonly-assigned combinations of rights. These are called combination rights. The defined combination rights are:

write
all rights but a (i.e. lidrwk)
read
l and r rights only
all
all rights (i.e. lidarwk)
none
no rights; this removes the group's or user's entry from the ACL entirely

Combination rights can be used in commands, as shown in the examples below.

A couple of notes:

Examining a Directory's ACL

You can examine a directory's ACL rights with the command: 

% fs listacl /path/to/directory

This returns a listing of all the users/groups that have any permissions on the directory, and what the permissions are. The directory path can be absolute (starting from root) or relative to the current working directory. For example, if you run the command: 

% fs listacl /afs/fnal.gov/files/wwwdocs/cd/webwg/tools

The system returns information in the format: 

   Access list for /afs/fnal.gov/files/wwwdocs/cd/webwg/tools is 
   Normal rights: 
     lauram:www_cd_webwg_tools rlidwk 
     nicholls:www_cd rlidwk 
     hanson:newsmachine rlidwka 
     nicholls:wwwdocs rlidwka 
     system:administrators rlidwka 
     system:anyuser rl

The group lauram:www_cd_webwg_tools has read, list, insert, delete, write, and lock permissions in this directory (all but administer permissions), i.e., the group has write rights. Any member of that group has these permissions in this directory.

Adding/Changing/Deleting a Directory's ACL

You can modify a directory's ACL for a particular AFS group or for an individual using the fs setacl command. The fs setacl command only changes the ACL for a single directory, not for a directory tree. The command syntax is: 

% fs setacl -dir /path/to/directory -acl <group> \ 
 <permission(s)>

where <group> is either a group or an individual username. When it is a group, it must be entered in the format <group_owner>:<group_name>.

We recommend that you generally define ACL entries for groups rather than individuals; it is much easier to maintain. When you need to add or remove permissions for an individual, it is easier to add/remove the user from one or more groups than to track down every directory for which the user appears in the ACL.

The directory path in the command can be absolute (starting from root) or relative to the current working directory. Any pre-existing permissions for the group or individual are invalidated; the specified permissions collectively become the new set of permissions. The permissions apply to all members of the specified group.

For example, in order to modify the ACL for the current directory (.) to include only read and lookup rights for any user (including unauthenticated users), enter: 

% fs setacl -dir . -acl system:anyuser rl

or, using combination rights syntax: 

% fs setacl -dir . -acl system:anyuser read

The group system:anyuser is described in section 9.7 AFS Protection Groups.

A note for Web page providers: set the permissions for system:anyuser to rl on directories containing files that you want to make accessible via a Web browser.

To remove all permissions in an ACL for a particular group (or individual), issue the fs setacl command with no permissions, e.g., 

% fs setacl -dir /path/to/directory -acl <group> ""

or, using combination rights syntax: 

% fs setacl -dir /path/to/directory -acl <group> none

9.7 AFS Protection Groups

An AFS protection group is a list of usernames grouped to share a set of permissions on one or more directories. Any user can include any existing protection group in any ACL within your AFS cell. A protection group is designated in the format:5

<group_owner>:<group_name>

AFS provides three predefined protection groups:

system:anyuser
This is similar to world permissions in UNIX. Any AFS user (anywhere in the world, and not necessarily authenticated) can access files or directories, according to the permissions granted (e.g., read, write).
system:authuser
This is a more restrictive version of system:anyuser. Only users who have authenticated within the local cell (/afs/fnal.gov at Fermilab) may access files, according to the permissions granted (e.g., read, write).
system:administrators
This group includes only the few people in the /afs/fnal.gov cell authorized to administer AFS.

As determined by your project's /afs area manager(s), you may need to manage, and possibly create, protection groups.

Groups can be owned by other groups or by individual userids. Group members often are not allowed to add or remove other members of the group. If a group is owned by a group, then all the members of the owner group can by default add or remove other members from the owned group. This can avoid problems when key individuals are unavailable. Having one group consisting of a few key individuals, and using this group as the owner for all your other groups is a nice, neat way to organize your groups. Find out from your /afs area manager how group ownership and permissions are assigned within your project or on your system.

AFS provides the pts command (protection server) for group-related tasks. Like the fs command, pts has several main options. Issue the command pts help to list the main options (the list shown here has been abbreviated to contain only the options we discuss in this section): 

pts: Commands are: 
adduser         add a user to a group 
chown           change ownership of a group 
creategroup     create a new group 
delete          delete a user or group from database 
examine         examine an entry 
listowned       list groups owned by an entry or zero id gets orphaned groups 
membership      list membership of a user or group 
removeuser      remove a user from a group 
setfields       set fields for an entry

A complete command reference can be found at the IBM Transarc® site under http://www.transarc.ibm.com/Library/documentation/afs/3.5/unix/cmd/cmd.htm.

9.7.1 Permissions for Performing Group-Related Tasks

Group characteristics (e.g., membership, ownership) can only be seen and/or modified according to the permissions set on the group. Here we present a brief explanation; more detailed information can be found at http://www.transarc.ibm.com/Library/documentation/afs/3.5/unix/cmd/cmd216.htm#HDRPTSSETFIELDS.

Every group has a set of five access flags, which represent permissions for performing sensitive tasks regarding (1) status, (2) ownership, (3) membership, (4) adding members, and (5) removing members. There is a pts main option associated with each of these tasks:

status (s)
pts examine
owned (o)
pts listowned
membership (m)
pts membership
add (a)
pts adduser
remove (r)
pts removeuser

Each flag has one of three possible values: its first letter in lowercase, its first letter in uppercase, or a hyphen. The value determines which users can issue the corresponding command option for the group as follows:

lowercase letter (s, o, etc.)
all members of the group
uppercase (S, O, etc.)
all users (i.e., system:anyuser)
hyphen (-)
group owner and members of system:administrators only

As an example, we'll issue a pts examine command and examine its output: 

% pts examine lisa:uss-group 

Name: lisa:uss-group, id: -316, owner: lisa, creator: hanson, 
membership: 14, flags: S-M--, group quota: 0.

The permissions information is contained in the flags entry. The flags S-M-- are the default flags when a group is created (all users can check status and membership information, only group owner and administrators can verify ownership and add/remove group members).

If you can't successfully issue one of the pts command options, check the access flags! Of course if you can't issue pts examine to check the flags, then you don't have status permissions for the group.

9.7.2 Listing Information about Groups

List Members of a Group

To list the members in a group, use the command: 

% pts membership <group>

For example: 

% pts membership lauram:www_cd_webwg_tools

returns the output: 

    Members of lauram:www_cd_webwg_tools (id: -454) are: 
       nicholls 
       hathaway 
       stolz 
       george 
       lauram 
       dwalsh 
       nelly
List Groups in which an Individual is a Member

To list the groups to which an individual belongs, again use pts membership, but with the user's id as the argument: 

% pts membership <username>

For example: 

% pts membership aheavey 

Groups aheavey (id: 6302) is a member of: 
  nicholls:www_reports
List Groups Owned by Group or Individual

To show what groups a particular group or user owns, issue the command: 

% pts listowned <group>

where <group> is actually either a group or an individual username. If you try to list groups owned by someone other than yourself, you may find that you do not have permission to do so.

Here are a couple of examples. To check groups owned by the group nicholls:wwwdocs, issue the command: 

% pts listowned nicholls:wwwdocs

Output is returned in the format: 

Groups owned by nicholls:wwwdocs (id: -306) are: 
  nicholls:www_cd_support 
  nicholls:www_cd_mgmt 
  nicholls:www_faw_events 
  nicholls:www_orgs_folkclub 
  nicholls:www_directorate 
  nicholls:www_cd_ups 
  nicholls:www_cd_webwg

To check groups owned by the individual user lauram, issue the command: 

% pts listowned lauram

Output is returned in the format: 

Groups owned by lauram (id: 1866) are: 
  lauram:wwwmachine 
  lauram:expwwwmachine 
  lauram:expwwwadm
Show Group Ownership

To find a group's owner, use the command: 

% pts examine -name <group>

This is helpful to determine if a group is owned by an individual or a group. For example, to find the owner of the group nicholls:www_reports, run the command: 

% pts examine nicholls:www_reports 

Name: nicholls:www_reports, id: -378, owner: nicholls:wwwdocs, creator: hanson, 
  membership: 5, flags: S-M--, group quota: 0.

Its output in the entry owner indicates that it is owned by a group (nicholls:wwwdocs), not by the individual nicholls.

9.7.3 Modifying Group Characteristics

Change the Owner of a Group

Note: It is best to change the owner of the group before you run fs setacl to add directory permissions for the owned group.

You can change ownership of a group using the command: 

% pts chown -name <owned_group> -owner <owner_group>

Let's take for example the group owner1:groupname1, where owner1 is an individual. We want to change its ownership to a group. The group we want to own it is designated owner2:groupname2. We issue the command: 

% pts chown -name owner1:groupname1 -owner owner2:groupname2

The owned group is now designated owner2:groupname1. Notice that it takes its owner designation from the owner group, and maintains its former group name. Here's a more real-life example for clarity: 

% pts chown -name lauram:www_cd_webwg_tools -owner \ 
 nicholls:wwwdocs

The old lauram:www_cd_webwg_tools is now designated nicholls:www_cd_webwg_tools.

You can change a group's ownership to itself (and set the group's access flags appropriately if needed) to allow all members of the group to add/remove other members and perform other administrative tasks. To change the group's ownership to itself, issue the pts chown command with the same group as both arguments: 

% pts chown -name nicholls:wwwdocs -owner nicholls:wwwdocs

The group designation <group_owner>:<group_name> does not change. If you need to reset the group's access flags, see the documentation on pts setfields at http://www.transarc.ibm.com/Library/documentation/afs/3.5/unix/cmd/cmd216.htm#HDRPTSSETFIELDS.

Note that there is a potentially confusing consequence of the way the group names change. All groups look like they're owned by individuals. You can always issue the command: 

% pts examine -name <group>

to determine if the owner is an individual or a group, as shown under Show Group Ownership in section 9.7.2 Listing Information about Groups.

Add a Member

To add a member, use the command: 

% pts adduser -user <username> -group <group>

For example: 

% pts adduser -user nelly -group lauram:www_cd_webwg_tools

The new member (nelly) must have an account on the system/cluster that mounts the AFS files he or she needs to access.

Remove a Member

To remove a member from a group, use the command: 

% pts removeuser -user <username> -group <group>
Create a Group

Check with your /afs area manager before creating new groups. As groups proliferate, system management can become more difficult.

To create a new AFS protection group, use the command: 

% pts creategroup -name <group>

or, leaving off the -name option flag for simplicity: 

% pts creategroup <group>

Always enter a group in the format <group_owner>:<group_name>; don't enter only the <group_owner> portion. By default, the group owner is yourself.6

As an example, user lauram could run the command: 

% pts creategroup lauram:www_cd_webwg
Remove a Group

To remove a group, use the command: 

% pts delete -nameorid <group>

For example: 

% pts delete -nameorid lauram:www_cd_webwg_tools

9.8 Implications of ACLs

The implementation of security in our Fermilab AFS cell is based on the notion that sharing information is more important than trying to protect it. Therefore, in most cases, the default has been to set ACLs to have the least security that is still reasonable. As currently implemented, all user home directories come with their ACL set so that system:anyuser has rl (read and lookup) permissions. A Mail subdirectory (used by the MH mail readers) is provided with more secure permissions.

The practical implication of this is that anyone on the internet running an AFS client can read your files, unless you change the ACL. Home directories are writable only by their owners (that is, the owner has rldiwka permission), but the world can read them. This is probably fine in many cases, but you should be aware of it and protect your files as you see fit, according to the guidelines presented below.

9.8.1 Protecting your Subdirectories

You can protect any single directory by changing its ACL to turn off permission for system:anyuser as well as for other users or groups that should be denied permissions. For example, if you use the mail reader pine, you may want to protect the message subdirectory mail. To make it completely inaccessible by system:anyuser, you'd issue this command: 

% fs setacl $HOME/mail system:anyuser none

On the other hand, if you need to allow others to write into any of your directories, the default permission is too constraining. Say you are in a collaborative effort with user mrchips. You could allow him full permission in your $HOME/shared directory by issuing the command: 

% fs setacl $HOME/shared mrchips all

Recall from section 9.6.2 Directory Permissions via Access Control Lists (ACLs) that if a user is in two or more groups that have different permissions on a directory, the user gets the union of the permissions.

Also, recall from section 9.6.2 that the fs setacl command only changes the permission for a single directory. If you have a directory hierarchy on which you want to change permissions, you'll have to use a UNIX command that traverses down the tree and changes all the directories as it goes. The find command can be used, but it must be used judiciously in the AFS environment! This is not recommended for inexperienced UNIX users (see section 9.10.2 AFS and the UNIX Command "find"). As an extension of the above example, say you had a directory hierarchy under $HOME/shared to which you wanted to allow mrchips full access. The find command could be used instead of fs setacl, as follows: 

% find $HOME/shared -type d -print -exec fs setacl -dir {}\ 
 -acl mrchips all \;

This would traverse down from the $HOME/shared directory, changing the ACL for each of the directories it finds. The -print argument causes the system to print out all the directories the command encounters, allowing you to monitor the progress.

Protecting your Home Directory

We strongly recommend that you make your home directory world readable, and simply keep your private files in protected subdirectories. That said, ...

... we do not recommend that you set the ACL on your home directory such that system:anyuser has no permissions (i.e., combination rights none) in order to keep your top level directory private. There are at least a couple of undesirable consequences:

If for some reason you really want to protect your home directory, you can do so to the extent that only l (lookup) permission is granted. However, you must make sure that any files that must be world readable, such as your .forward file, remain accessible. Be aware that it is not always obvious which files must remain world readable in order to preserve the behavior of your environment. You can protect your home directory as follows (Proceed with caution!):

  1. Every AFS home directory is created with a subdirectory called public. Move the files that must remain world readable into this directory.
  2. For each file moved into public, create a symbolic link in your home directory to the file in the public directory. Use the same filename.
  3. After all the necessary files are moved and linked, then shut off all permissions except l (lookup) on your home directory.

Note that you must leave the l permission turned on or programs won't be able to find the file in public via the symbolic link.

Here is a sample session, assuming the only file that must remain world readable is .forward (there would actually be many files). It would be run from the user's home directory: 

% mv .forward public/.forward 
% ln -s public/.forward .forward 
% fs setacl . system:anyuser l

9.8.2 AFS in Translator Mode

If your machine is accessing AFS via a translator node, you do not get authenticated when you log in, and in fact you can't run the pagsh or klog programs discussed in section 9.3.1 Authentication in AFS. You cannot access your AFS login area. You only have access to directories for which an ACL is defined for system:anyuser. You have access to files in those directories according to the ACL entry for system:anyuser and the file owner bits, as usual.

At Fermilab most of the UPS products are set with read permissions (rl) for system:anyuser, thus allowing access to products maintained in the /afs products area from a machine running in translator mode. This is not true for products that are site-licensed (e.g., edt), which are made accessible only to users on site.

9.9 File Locking in AFS

The file locking mechanism in AFS does not really follow POSIX semantics. There are a few issues to mention:

Generally we don't recommend including applications that depend on file locking in the AFS file space. Contact the help desk at http://csdserver1.fnal.gov/HelpDesk/cd/ for more information or for resolution of a problem.

9.10 Frequently Asked Questions

9.10.1 Lost Access to Files

Why can't I access files I'm supposed to be able to edit?

First see what permissions you have by checking:

Remember that authentication lasts only a set period of time (six days in /afs/fnal.gov). If your authentication has expired, you will not have access to your files. You can reauthenticate by running pagsh and klog (see notes in section 9.3.1 Authentication in AFS). Also we encourage you to use ssh in (which always authenticates to AFS) instead of using telnet. See section 9.3.4 Managing your Token and, if kerberos is installed, the Strong Authentication at Fermilab Manual at http://www.fnal.gov/docs/strongauth/index.html for information on these utilities. If you use eXceed, note that rexec does not work with AFS.

9.10.2 AFS and the UNIX Command "find"

Why shouldn't I use "find" in AFS space?

You should be very careful about using any command that traverses the file system on a machine that has /afs mounted. Be aware that a find on your system starting at root (/) will traverse the whole AFS file tree, including all the other AFS sites mounted on our cell. This is particularly problematic on some workstations, like Solaris 1 Suns, which by default run a nightly cron job that traverses the whole file system. Also note that the -mount and -xdev options (e.g., find / -mount ... -print) won't recognize an /afs file system boundary; find can't tell the difference between local files and AFS files.

9.10.3 Error Messages

What does it mean if I get an error message like this: 
afs: Waiting for busy volume 536870945 in cell fnal.gov

This is an error message from AFS that indicates that you are trying to access a volume that is busy. There may be a number of perfectly normal reasons for this. It generally means that either your volume is in the process of being cloned for a nightly backup, or one of the system administrators is in the process of moving your volume to a different disk because the one you are on is filling up. Normally the process that generated the error will just hang harmlessly for a few minutes until whatever locked the volume is finished. If this goes on for more than 20 minutes or so, contact the help desk and inquire about what is going on.

9.10.4 Retrieving Old Files

What if I need to retrieve yesterday's copy of a file?

Daily backups of the entire Fermilab cell are available from /afs/fnal.gov/files/backup/. For example if your home area is /afs/fnal.gov/files/home/room3/joe, you should be able to find yesterday's files in /afs/fnal.gov/files/backup/home/room3/joe. The backups are done at 12:45 a.m. seven days a week.

If you cannot locate your files, contact the help desk to request that your backup volume be mounted so that you can access it.

9.10.5 Link Failure

Why did my link fail?

Hard links can be used only within an AFS volume, not across volumes. Generally, you should use symbolic links.

1
In translator mode, a "translator machine" runs AFS and exports the AFS file tree to other systems via NSF.

2
If your token has expired within the previous two hours, you do not need to run pagsh before klog.

3
If you are on a non-FNALU node, check with your system administrator before running these utilities.

4
This is set up with the usual UNIX method of using /etc/hosts.equiv or .rhosts to equivalence systems.

5
You may encounter groups that do not have an owner prefix; these are special groups created by the system administrators.

6
There is an option (-owner) to set the owner to another individual or a group, but we recommend that you just use chown afterwards as described in section 9.7.3 Modifying Group Characteristics.