Jump to: Overview

Introduction to AFS

What is AFS?

AFS is a distributed file system similar to a Windows or UNIX file server that allows Windows and UNIX computers to use the same file space. Casual Windows and UNIX users will see little difference between working with files on the local hard drive and working with files stored in AFS space. AFS can serve as a central place to store files for you or your department, which are then available from any computer, Windows or UNIX, running the AFS client software. Additionally, AFS offers more advanced users enhanced capabilities to manage file permissions, group access to directories, and disk quotas.

Getting Help

The AFS client for Windows includes an online manual. Assuming that you have the AFS client software installed, the documentation can be found in HTML format in the IBM AFS program group under the Start Menu as such:

Windows 2000/NT: Start > Programs > OpenAFS > OpenAFS Help

Windows XP: Start > All Programs > OpenAFS > OpenAFS Help

For help on installing the AFS product, please see the Getting Started with AFS document.

Getting Help for AFS Commands

You can get online help for AFS commands from both a UNIX and Windows command prompt. AFS fs and pts commands are used to manage files/directories and AFS groups, respectively. For example, to get information on how to add a user to a group, try typing the commands below.

Basic help usage (Windows and UNIX): pts help or fs help

The command line options will show you each possible command. Help can then be used on the specific command within the command suite you've chosen. For example, you can get help for the listquota command by typing fs help listquota.

Managing Access Control Lists (ACLs)

Every directory in AFS space has a corresponding ACL which determines the level of access or restriction for any files within the directory. Let's examine these privileges as well as the AFS commands used to manage them.

We use the fs (fileserver) command suite to work with ACLs. The usage of the fs setacl command is as follows:

fs setacl -dir <directory> -acl <access control entries> [-clear] [-negative] [-id]

The following command lists the ACL for the current directory (given that the current directory is a directory in AFS; you will receive an error if you run the command on a local directory).

H:>  fs  listacl

Access  list  for  .  is

Normal  rights:

system:anyuser  rl

newton  rlidwka

In most fs commands, there is a -path option that allows a user to specify a particular directory. Most fs commands assume a default path of the current directory.

To designate user permissions, ACLs use seven different attributes as well as four shortcut forms consisting of combinations of these attributes. Generally, most users will want to manage ACLs with the shortcuts rather than the individual forms.

The seven ACL attributes are as follows, and can be used in any combination. The shortcuts are listed afterward, can only be used on at a time, and should suffice for most users' needs. It is also possible to designate a "negative" option, which denies that attribute to a user or group.

Table 1. ACL Attributes

Attribute	Function
read (r)	Allows possessor to view the contents of files.
lookup (l)	Allows a user to view the contents inside of a directory (for example, with the Windows dir or UNIX ls command), to view the ACL, and (in Windows) to mount a drive.
write (w)	Allows modification of files and the use of the UNIX chmod command. Users should generally be granted lock (k) when given this permission. See
insert (i)	Allows the user the right to add new files and subdirectories.
delete (d)	Allows user to remove files and subdirectories (if they also have read; additionally, list is required to see the file in a directory listing (dir or ls)
lock (k)	Allows user the right to run programs which place locks on files. This permission allows the user to "check out" files for editing; it should usually be granted to anyone with write (w) access to a directory. See AFS File Locking Issue for information on the impact of trying to write files without (k).
administer (a)	Allows possessor to change the directory's ACL.

Table 2. ACL Shortcuts

Shortcut	Function
read	Grants permissions to look at contents of directory and files. Equivalent to "rl" permissions.
write	Grants permissions to read, write, modify, and delete files and directories. Equivalent to "rlwidk".
all	Grants full permissions, including the ability to change AFS ACLs. Equivalent to "rlwidka".
none	Removes all permissions of a user or group. This should be used to remove a user or group's entry from the ACL. Keep in mind that if they are in a group with permissions on that directory, they will retain the permissions of that group, unless you explicitly deny them with negative permissions.

NOTE: administer is a default privilege for any user's home directory and all associated subdirectories.

Here's an example of the fs setacl command:

H:\> fs setacl . morris rl newton rlidwka

In this case, morris has permission to run the ls command, access the ACL, and read files. User newton has full rights to the directory. The same results could have been attained with this command:

H:\> fs seta . morris read newton all

To remove a user or group's entry from the ACL, issue:

H:\> fs seta . morris none

Once this command is issued, morris would no longer have any explicit permissions on the directory. Keep in mind that if morris were part of a group that had permissions on the directory, he would keep the group's permissions.

Everything up to this point has concerned itself with normal rights, the default mode. You can also apply negative rights. With the use of negative rights, it is possible to allow a group one set of permissions, while curtailing the rights of certain members in that group.

The command below denies the user morris the ability to delete (d) and write (w) in the directory to which the ACL applies.

H:\> fs setacl . morris wd -neg

The command below first clears all entries in the ACL, then gives user newton all privileges. If newton had existing permissions prior to this command, they would be discarded in favor of those specified, in this case "read".

H:\> fs setacl . newton read -clear

Here's a real-world example of using -clear, as this can be somewhat confusing.

H:\>  fs  listacl  .

Access  list  for  .  is

Normal  rights:

    system:administrators  rlidwka

    system:anyuser  rl

    newton  rlidwk

    morris  rl

H:\>  fs  setacl  .  newton  read  -clear

H:\>  fs  listacl

Access  list  for  .  is

Normal  rights:

    newton  rl

It is also possible to copy an ACL from one directory to another. Here is an example:

H:\> fs copyacl -fromdir /home/newton -todir /home/morris

This command also works if you specify a filename rather than a directory. In such a case, it simply reads the ACL from the directory containing the file specified, then copies that to the new directory's ACL.

Remember, the role of the UNIX mode bits has changed; only the left most three permissions bits (i.e., owner) apply. Even if the directory's ACL has write permission for a given user or group, if the owner write bit is off, no writes will be allowed to the file. If you copy a file from one directory to another, the file takes on the permissions found on the new directory's ACL.

On Windows systems, ACLs can also be managed graphically. To view or modify the ACL on a folder, simply right-click the folder in Windows Explorer, select AFS, the Access Control Lists. This will bring up the following screen:

You can then use the buttons on the right of the dialog box to add/remove groups and modify their access attributes on the folder.

Adding Groups to ACLs

In an ACL, you can apply permissions for individual users or groups of users. In this regard, you should be aware of a few security considerations. If you add a group that is owned by someone else, the owner of that group can change the members of that group without consulting you. Thus, someone new could gain unwanted access to your files.

Managing Your Directories in AFS

A major difference between AFS and standard Windows/UNIX filesystems is found at the directory level. AFS allows each user a greater ability to decide how they wish their files accessed. In Windows NTFS filesystems, one used the Security tab of the desired file/folder's context menu Properties. In UNIX, the chmod command is used. While these utilities are still used for files not stored in AFS, there is a mechanism called the Access Control List, or ACL, that governs directory access. Also keep in mind that access (or lack thereof) is controlled at the directory (or folder) level, not at the file level as it is in standard Windows/UNIX filesystems. In most ways, controlling access is easier than in the standard way since one only needs to worry about security in one location. On the other hand, one must remain aware that changing individual security attributes with NTFS or chmod commands may not provide the level of security you desire.

AFS Groups

In Windows (Windows NT/2000) and UNIX, every user is a member of at least one group. Groups are used to apply special privileges or restrictions to a subset of users. AFS takes this concept and expands on it. In AFS, groups are mechanisms by which specific users can be targeted with specific file permissions for specific directories. When you create an AFS group, you gain both ownership of the group and administrative control of that group.

A group can be self-owned, meaning all members of the group have administrative rights. While this helps in the day-to-day maintenance of the group, it could have adverse effects. If everyone in the group has administrative rights, it is possible for the original creater/owner of the group to be removed from it by another member of the group.

Groups make the management of ACLs simple. Rather than adding and removing individual users from each ACL, it is easier to manipulate them through their group membership, thus updating any ACL that includes this group.

Managing Groups in AFS

While there is no quota on the number of groups to which you can belong, there is a quota on the number of groups you can create. 20 groups is currently the maximum. Group names can be up to 63 characters in length and cannot contain colons, blank spaces or capital letters. The group name usually takes the form of:

Onyen:group-name

In AFS, we use the pts command to work with groups. Below is a list of the pts commands:

Command	Description
adduser	add a user to a group
apropos	Search by help text
chown	change ownership of a group
creategroup	create a new group
createuser	create a new user (administrators only)
delete	delete a user or group
examine	examine an entry (get details on user/group)
help	get help on pts commands
listmax	list maximum userID and group numbers
membership	list membership of a user or group
removeuser	remove a user from a group
rename	rename a user or group
setfields	set fields for an entry
setmax	set the maximum userID number

The command pts creategroup makes you the owner of a new empty group. For example:

C:\>  pts  creategroup  newton:first

Group  newton:first  has  id  -2610

This command works from a Windows or UNIX command prompt. Note that omitting the username causes an error:

C:\>  pts  creategroup  second

pts:    badly  formed  name  (group  prefix  doesn't  match  owner?)  ;  unable  to  create  group  second

The group name prefix can also be a group, and a group that you create can be owned by another group. That is, instead of all groups being named with an onyen, a group can be used. For example, a new group containing programmers within the Foo group might be called foo:programmers. Prefixing a group name with another group makes it easier to deal with staffing changes, and makes individual's Onyens unimportant. For example, if the group name was newton:programmers, and that onyen was expired, it might be confusing for some that need to use the group, or who were unnecessarily restricted by it. For groups used for your personal purposes or to manage personal space, the standard onyen:groupname format is probably appropriate. If you manage departmental resources in AFS, you may want to consider an alternate naming scheme.

The next few commands are useful for managing groups. The first command adds a user to the group (yourself, perhaps). NOTE: Creating a group does not automatically make you a member of that group.

C:\> pts adduser newton newton:first

The pts membership (or pts mem) command shows group membership information:

C:\>  pts  mem  newton:first

Members  of  newton:first  (id:  -2695)  are:

newton

morris

jennyw

To find out more about a particular user and, try the pts examine command. The examine argument returns the group owner and the creator of the group. The first example returns details of a user, the second returns details of a group:

C:\>  pts  examine  newton

Name:    newton,  id:  3203,  owner:  system:administrator,  creator:  admin,

Membership:  9,  flags:  S----,  group  quota:  20.

C:\>  pts  examine  newton:first

Name:  newton:first,  id:  -2695,  owner:  newton,  creator:  newton,

membership:  0,  flags:  S-M--,  group  quota:  0.

The next command shows all groups that are owned by this user or group:

C:\>  pts  listowned  newton

Groups  owned  by  newton  (id:  3203)  are:

newton:first

newton:second

newton:third

The following command removes a user from a group:

C:\> pts removeuser jennyw newton:first

The following command deletes the group entirely:

C:\> pts delete newton:first

Checking Your Quota in AFS

AFS stores subtrees of related files and directories in an entity called a "volume". This logical partitioning is useful for backing up the system. The files in your home directory are generally stored together in a single volume. To divide the disk space in a volume as fairly as possible, the system administrators impose a quota on each volume. To find out if you are approaching the quota limit on your volume, use the following AFS commands, each shown with a sample response.

The command fs lv [-path] lists the current volume status for the named directory. The difference between the maximum quota and the number of blocks used is what remains available.

H:\>  fs  lv  .

Volume  status  for  vid  =  536871815  named  user.newton

Current  disk  quota  is  256000

Current  blocks  used  are  45839

The  partition  has  8550436  blocks  available  out  of  10616832

The command fs listquota [-path] is similar to fs lv.

H:\>  fs  listquota  .

Volume  Name                                        Quota              Used      %Used      Partition

user.newton                                      256000            45839      18%                  19%

The command fs quota [-path]shows just the percentage of quota used.

H:\>  fs  quota  .

18%  of  quota  used.

On the Windows platform, you may also use the AFS context menu for the directory's Properties to view quota information. Right-click a folder in the volume for which you want the quota information then select AFS > Volume/Partition > Properties . You will see a dialog box similar to the following:

Getting Volume Information

You can get additional information concerning your volumes with the fs examine command.

H:\>  fs  examine

Volume  status  for  vid  =  536871815  named  user.newton

Current  disk  quota  is  256000

Current  blocks  used  are  45839

The  partition  has  8550436  blocks  available  out  of  10616832

Another command which can be useful is the fs whereis command. This command will show you the AFS server name that contains the file or folder you specify.

For example, if a change notice were sent out to announce downtime for one of the AFS fileservers, you could check to see if the files you work with are on that server. The format of the command is fs whereis <path>.

Windows:

C:\>  fs  whereis  J:\isis\scratch

File  j:\isis\scratch  is  on  host  fs4.isis.unc.edu

UNIX:

%  fs  whereis  /afs/isis/scratch

File  /afs/isis/scratch  is  on  host  fs4.isis.unc.edu

Retrieving Lost Files

How often have you made a mistake which resulted in a plea to the ITRC or your system administrator to restore a lost file? In AFS, a one-day-old backup of all your files in automatically maintained online, and you can retrieve these files yourself. This online backup is only of your user volume, not any departmental or application volumes you may have. These snapshots of your home volume are taken once every night. Departmental volumes are also backed up nightly, but data is restored from these volumes in a different way. Please contact the IT Response Center at help@unc.edu or (919) 962-HELP for assistance with restoring data from other types of volumes.

Your home directory in AFS contains a directory (a mount point actually) called OldFiles which contains all of the files that were in your volume the day before. To restore files in OldFiles to your regular volume, simply use normal Windows or UNIX copy utilities (copy, cp, or Windows Explorer).

H:\>  cd  OldFiles

H:\OldFiles>  copy  important.doc  H:\

-or-

%    cd  OldFiles

%    cp  important.file  ..

About help.unc.edu