Home >  Software & Computers > Data Storage >  AFS >

Installing OpenAFS Client on Mac OS X

Research Computing recommends versions 1.6.2 or higher.

• Installing the OpenAFS Package
• Tuning the AFS Client
• Authenticating to AFS
• Changing the Macintosh Username and UID to Match AFS

Installing the OpenAFS Package

1. Download OpenAFS 1.6.2 or higher. This is a (local) disk image file (.dmg). Alternatively, you can download the latest version from the OpenAFS website.
2. If the Disk Image does not automatically mount, double-click to mount it as a volume named OpenAFS.
3. Double-click the enclosed OpenAFS.pkg package to start the installer. You will be asked for your password (you must be logged in as an administrative user) and to accept the license agreement. Installation will take about a minute, and will prompt for a default cell name;  enter northstar.dartmouth.edu.  The client will start running immediately, but rebooting is recommended.
4. The default settings will allow access to the Dartmouth (northstar) cell, with client options which will work in almost all cases. The client tuning described below may improve performance, and will set up the client to automatically track changes to our servers and be easier to use in our environment.

To do a clean uninstall of OpenAFS client, use the uninstall program that comes bundled with the installer.  You  can also use OSXPM, a free package management tool for Mac OS X, and use it to remove the OpenAFS package.

Top of page

Tuning the AFS Client

Configuring the AFS client settings may be performed by downloading and running afssetup. Unpack the .zip file if your browser doesn't do this automatically, then double-click the resulting afssetup.command script to execute it, and enter your password when prompted. This script will update the configuration with the recommended Dartmouth settings and start the AFS client, and also create Desktop shortcuts to your AFS volume(s).  The shortcuts may be recreated at any time by running the afslink.command script.

You should now have an AFS icon on your desktop. Double-click the icon to browse AFS space. Alternatively, you can start up a Terminal window. AFS space appears under /afs. After a reboot, the AFS client should start automatically.

Alternatively, you can hand edit the configuration files in /var/db/openafs/etc. The afssetup script does the following, as root.

1. Creates a file called ThisCell that contains the single line northstar.dartmouth.edu.
2. Creates a file called config/afs.conf that contains the recommended client options.
3. Turns on crypt mode, so that filesystem traffic to AFS is encrypted in transit.  The authentication steps are always encrypted.
4. Truncates CellServDB to a zero-length file. Most users do not need it; it can cause problems if it contains invalid data (but the file must exist).

You may also want to edit /var/db/openafs/etc/cacheinfo and change the 30000 to something larger. This is the size, in KB, of the local cache used to store AFS files and reduce the amount of network I/O needed.

The cell server address information, for cells not using DNS, lives in /var/db/openafs/etc/CellServDB. If you need access to other (off-campus) cells in the world-wide AFS community, contact Research Computing for assistance.

You can also manually start and stop the AFS client, as long as no processes have open files in AFS. Clickable start and stop tools are also in the afssetup zip file.

Top of page

Authenticating to AFS

You now have access to AFS space, but you do not have permission to see your own personal files yet. You can authenticate to AFS by manually running the klog utility in a Terminal window, giving it your AFS username and password when prompted, or by clicking on the padlock icon which should be at the top of the screen.  When you are authenticated, the padlock will have no red 'X'.  You will now have full access to your files in AFS through the finder or the command line. However, you may not see your own name as the apparent owner of the files, but this usually does not matter. You now have an AFS token (limited lifetime Kerberos ticket with AFS access privileges).

% klog afsusername

You can change your AFS password with the kpasswd.afs utility. 

% kpasswd.afs afsusername

Top of page

Changing the Macintosh Username and UID to Match AFS

Most users will not need to perform the following steps, but it may be useful to synchronize your user account details on the Macintosh with those in AFS, or even to configure the Macintosh to use your AFS directory as your home directory. Obtaining AFS credentials at login time is outside the scope of this document. The following steps are intended as a guide for experienced users only.

1. If your user name on the Macintosh is not the same as your AFS user name, you will need to create a new user account on your Macintosh that has the same name as your AFS name. You will then need to add that user to the groups you currently belong to on your Macintosh. (If your Macintosh user name is the same as your AFS user name, you can skip this step.)
   1. Open the Users Account manager by selecting System Preferences, Accounts, then New User (+). Create a new user with the same name as your AFS name.
   2. Open a Terminal window.
   3. Enter /usr/bin/id. It will print a list of the groups you currently belong to.
   4. Open up the NetInfo utility's group pane by selecting Finder, Applications, Utilities, NetInfo Manager, then Groups. Click the Lock icon in the lower left-hand corner and enter your admin passwd so that you can make changes. Add your AFS user name to all of your current Macintosh groups.
   5. From a Terminal window, copy over all the files from your old Macintosh user name directory to the account you just created: % sudo cp -pR /Users/old-mac-username/* /Users/afs-username.
   6. Log out and log back in under your AFS user name.
2. Change the uid of the AFS user name on the Macintosh to match your AFS uid. To do this, open the NetInfo utility user's pane by selecting Finder, Applications, Utilities, NetInfo Manager, then Users.
   
   1. Click the Lock icon in the lower left-hand corner and enter your admin passwd so you can make changes.
   2. Double-click on your AFS user name.
   3. Change the value for the uid to be the same as your AFS uid. (Your AFS uid can be found from the Terminal window with the command /usr/bin/pts examine afs-username.
      
      In the id: number field, number is your AFS uid. Be sure to write down your current Macintosh uid, since you will need to provide it in the next step.)
3. Change ownership of all your files on the Macintosh to your AFS uid. To do this, open a Terminal window and enter % sudo find / -xdev -user old-mac-uid -print -exec chown new-afs-uid {} \;.
   
   This could take a few minutes to complete, depending on how big your system is. Be patient! When find has finished, issue a klog command to be sure you have a token. Make sure you can access your AFS file space through the GUI (the AFS icon on your desktop).
   
   Note: When you log in for the first time after a reboot, you will not have a token. You will need to klog to get a token. Tokens are preserved when you log out and back in, however.
4. Clean-up: If you created a new Macintosh user account in step 1 above, you may want to delete the old one at some point. It is best to keep it around until you are sure everything is working correctly. At that point, you can delete the old account as follows:
   1. Open up the Users System Preferences by clicking System Preferences, then Users.
   2. Click the lock icon in the lower left-hand corner and enter your admin passwd so you can make changes.
   3. Click on your old Macintosh user name.
   4. Click the Delete button
   Top of page