Tuning the AFS client for Macintosh

Details

Below are optional configuration and tuning steps for the OpenAFS Macintosh client.

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.

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