The University of North Carolina at Chapel Hill
College of Arts and Sciences
Department of Computer Science

Introduction to AFS at UNC			

reviewed by John Sopko 3/22/2009


This is one of several AFS howto pages.  Their titles are listed below
in the recommended reading order:

+1)afs-intro -> basic concepts on AFS and AFS command structure
 2)afs-security -> overview of permissions and groups in AFS
 3)afs-volumes -> discussion of how AFS volumes and backups work
 4)afs-tips -> common questions and advanced techniques with AFS

Resources on AFS
----------------

See the following web page for info on how to get to the OpenAFS online
html manual. The "AFS Users's Guide" is an excellent manual for beginners!

http://www.cs.unc.edu/help/afs_info

The department is running OpenAFS:

http://openafs.org

AFS is strictly open source and we have no support for the product other
then the openafs.org mail lists.


Intro
-----

AFS is a distributed file system.  It uses the client/server model, 
where all the files are stored on file server machines.  Files are 
transferred to client machines as necessary and cached on local disk. 
The server part of AFS is called the AFS File Server, and the client 
part of AFS is called the AFS Cache Manager.  AFS provides Access 
Control Lists (ACLs) which provide for more control and flexibility 
than standard UNIX file permissions.

AFS is an alternative to NFS as a mechanism for sharing files.  
Currently NFS provides semi-transparent access to files on several 
file servers within our Department.  AFS provides a mechanism to 
provide transparent access to files both within our Department and 
within the world Internet community.

AFS provides transparent access to local and remote files by using a 
consistent name space.  All files in AFS are found under the UNIX 
directory /afs.  Under the /afs directory are the various sites 
which run AFS and make their file-system available to the Internet 
community. These sites are called AFS Cells.  We are an AFS cell, 
and our cell name is the same as our Internet name, cs.unc.edu.  
Thus, all of our AFS files are in /afs/cs.unc.edu.

This use of a common name space means that a user can specify the 
full path name of an AFS file, and have it be valid on any computer 
system using AFS.  Therefore, if I'm using AFS here at Chapel Hill, 
and working with someone at another AFS cell, we can both work with 
the exact same file, using the same name.  For example, the command 
'more /afs/cs.unc.edu/home/user1/x-program.c' works the same whether 
the user is here at UNC Computer Science Department or at another AFS 
cell site.  Of course the user must have permission to read the file.

It is important to realize that AFS and NFS are separate file systems. 
AFS provides different security, performance, and commands to manage 
directories and files, and those commands and features work only on 
files in the AFS name space.  While we are running both filesystems 
there will be mechanisms for accessing AFS files in NFS name-space 
and NFS files in AFS name-space.  AFS files and NFS files reside on 
separate physical disk space. 


AFS and UNIX

AFS works with various UNIX operating systems and flavors of Windows. The AFS
cache manager handles the details of communicating with the AFS
servers, checking the security and permissions, and managing the local
disk cache. The UNIX applications simply see a normal UNIX file.


AFS differences from UNIX file systems

The major differences between UNIX 
and AFS file systems are:

1.  Protection mechanisms
-Access control lists are used to control protection.
-Protection is at the directory, not file level.
-Users can create and maintain their own groups.
-AFS pts commands replace chmod and chgrp commands.

2.  Authentication mechanism
-Users must hold a valid "token" to access their home directories.
-Tokens have a fixed lifetime and must be refreshed when they expire.


AFS shortcuts

All files at UNC under AFS can be found through the directory 
/afs/cs.unc.edu.  To make local path names shorter, a symbolic link 
exists from /afs/unc pointing to /afs/cs.unc.edu, so locally /afs/unc 
can be used.  These shortcuts can not be used from machines outside 
the cs.unc.edu domain.


AFS binaries

There are several programs which you will need to use AFS.  These 
programs are found in /usr/afsws/bin.  You should add this to your 
path in your .login and/or .cshrc files.  There are also some 
administrative commands in /usr/afsws/etc.  If you work with volumes 
frequently you may want to also add /usr/afsws/etc to your path.


AFS home directories

All of our department's home directories are in AFS and are accessable as
/afs/cs.unc.edu/home/login, where login is replaced with your actual 
login name.  Home directories are also accessible as ~login.


Accessing foreign cells

One of the benefits of AFS is the possibility for long distance 
collaboration.  A number of remote AFS sites are accessible on our 
workstation simply by typing 'cd /afs/cellname'.  An ls in /afs will 
show all accessible cells.  If you normally alias ls to "ls -F", 
either unalias it for this command, or use \ls.  "ls -F /afs" will 
contact each cell to get some information, and it takes much longer 
than "\ls /afs."

If a remote cell is not listed that you wish to access please email
help@cs.unc.ed describing the cell you wish to access and we will
configure the cell into AFS.


Changing your password

Use the normal https:/www.cs.unc.edu/webpass page to change your AFS 
password.  This will change your AFS, UNIX, and Windows passwords.  Please 
report any problems with this to the Technical Support Center or help.  
See howto password-change for more info.


Using AFS

Most of the time when you use AFS, you will use it just like an NFS or 
UNIX file system.  Occasionally, since AFS provides features not 
available on UNIX and NFS file systems, you'll want to use specific AFS 
commands for managing your files under the control of AFS.  

The AFS command used most is the "fs" command. Fs is actually a whole
set of commands which manipulate files and directories under AFS. To
see all the different commands available under fs type:

    % /usr/afsws/bin/fs help

You'll get back a list of about 50 commands.  A few of the more useful ones are:

    apropos		search by help text 
    cleanacl		clean up access control list 
    diskfree		show server disk space usage 
    getcellstatus	get cell status 
    help		get help on commands 
    listacl		list access control list 
    listcells		list configured cells 
    quota		show volume quota usage 
    setacl		set access control list 
    whereis		list file's server

To find out how to use these commands type 'fs command_name -h'.
For example:

    % fs diskfree -help 
    Usage: fs diskfree [-dir <directory>+] [-help ]

The dash is important in front of the help, so 'fs diskfree' 
doesn't think you are trying to find the free space available on 
the help directory.

The AFS fs command can be abbreviated to the shortest possible 
unique name, e.g., "fs checkvolumes" becomes "fs checkv", 
"fs checkservers" becomes "fs checks", and "fs cleanacl" becomes 
"fs cl." A few pre-defined aliases already exist, the most 
common of these is listed below.

"fs listacl" has been aliased to "fs la":

    % fs la /afs/unc/home/user1 
    Access list for /afs/unc/home/user1 is 
    Normal rights:   
      system:anyuser rl   
      user1 rlidwka
    
Similarly "fs setacl" has been aliased to "fs sa".

"fs diskfree" has been aliased to "fs df":

    % fs df /afs/unc/home/user1 
    Volume Name       kbytes  used     avail      %used
    D0.home.user1    425447    329732   95715    78%