Advanced Topics and Troubleshooting

The topics covered elsewhere in this guide are sufficient for most situations. Here is additional information about OpenAFS as well as technical details to assist in resolving problems that are less commonly encountered.

Basic troubleshooting checklist for OpenAFS

If you are having difficulty, use the following checklist to help pinpoint the problem.

• Did you restart your computer? If not, restart and try again to access your files.
• Did the install procedure work correctly?
• Is your clock synchronized with the time server at NC State?
• Can you get Kerberos tickets?
• Do you have AFS® tokens?
• Is AFS mounted?
• Do you have folder access privileges?
• Can you copy a file from one folder to another?
• Do applications sometimes crash when you save or open files?
• Do your text files transfer incorrectly?
• Are your Web pages inaccessible?

If you’ve tried all the applicable items in this list but are still having a problem, contact the NC State Help Desk.

What the OpenAFS installer does

• Configures Kerberos using two NC State-specific files:
  • /Library/Preferences/edu.mit.Kerberos
  • /Library/Preferences/edu.mit.Kerberos.KerberosLogin.plist
• Installs Open AFS
• Configures OpenAFS for use at NC State by installing five files:
  • /private/var/db/openafs/etc/ThisCell
  • /private/var/db/openafs/etc/TheseCells
  • /private/var/db/openafs/etc/CellServDB
  • /private/var/db/openafs/etc/config/afsd.options
  • /Library/StartupItems/OpenAFS/OpenAFS
    NOTE: The installer configures OpenAFS for use only within NC State’s AFS® cells. NC State’s Office of Information Technology does not recommend configuring OpenAFS to access all AFS® cells worldwide.
• Puts these files and folders on your hard drive:
  • uidMatch, afstokens and Mount_AFS into your /Applications folder
  • aklog into your /usr/bin folder
• Creates a Kerberos plugin directory in /Library containing the file aklog.loginLogout
• Puts AFSCMPlugin into the /Library/Contextual Menu Items folder

Synchronizing your MacOS X UID with your AFS® UID

It may be a good idea to synchronize your local MacOSX UID with your AFS® UID to avoid issues with some application programs. There are two ways to accomplish this. The easiest way is to use the uidMatch application in the OpenAFS software that you downloaded:

1. Open your Applications folder and double-click on the uidMatch application inside it.
   
2. In the window that appears, select the Run button.
3. Choose from list as the method of name selection.
4. Choose your ID from the list that appears.
5. Choose the method of external uid discovery by selecting afs tools.
6. The next window will show your AFS UID. Verify this if desired by using the Terminal as noted in steps 1 through 4 of the alternative procedure below.
7. Select OK.
8. In the next window select OK.
9. Authenticate by entering the password for your local machine account.
10. The program will now scan your hard drive, making the UID changes. This may take as long as 30 minutes, depending on the size of the hard drive and the number of files to be changed.
11. When the changes are completed, you should see a window with the message: “Finished with no apparent errors.”
12. A log file of the changes is created and stored in /tmp/uid_match_results.

Alternatively, you can synchronize your two UIDs using the Terminal and AFS® commands:

1. Open a Terminal window.
2. Type:
   pts examine userid
   after you have replaced userid with your Unity ID.
3. You will see a block of text that begins with:
   NAME: userid, id:12345....
   where userid is your Unity ID.
4. The number following “id:” (in this example, 12345) is your AFS® UID.
5. Open the NetInfo Manager, found on your hard drive at /Applications/Utilities/NetInfo Manager
6. In the window that appears, select users in the middle panel.
7. Click on the padlock icon in the lower left hand corner.
8. Authenticate as an administrator by entering your password.
9. Click on your user name in the right hand panel.
10. You will see a number in the Value(s) column that is next to uid in the Property column.
    NOTE: Be sure to record this number (your MacOS X UID) before you proceed in case you need to change back to it.
11. Double click on this number and change it to your AFS® UID.
12. Click on the padlock icon to prevent further changes.
13. Select Yes when asked if you want to update the file.
14. Open /Applications/Utilities/Terminal.
15. Type:
    sudo -s
    and enter your password when prompted.
16. Type:
    /usr/bin/find  / -xdev -user macosuid -exec chown afsuid {} \\;  -print
    after you have made these two changes in this command:
• macosuid to your MacOS X UID (from step 10)
• afsuid to your AFS® UID (from step 4).
17. Press RETURN.
18. This may take up to 30 minutes if you have a large hard drive.

Synchronizing your computer’s clock with NC State’s time server

It is crucial that your computer’s clock be set to within three minutes of the time server. To do this,

1. From the Apple menu, open System Preferences.
2. Select Date & Time.
3. Select the Time Zone tab.
4. Choose New York - U. S. A. from the list of cities.
5. Select the Date & Time tab.
6. Make sure the Set Date & Time automatically checkbox is marked.
7. Type time.ncsu.edu in the text box.
8. Close the Date & Time window.
9. Quit System Preferences.
10. To verify that the clock was synchronized, re-open System Preferences and check the date and time shown in the window.

Copying from one folder to another doesn’t work

This kind of copying problem usually occurs because the AFS® folder privileges have not been set correctly. You must have Read, Lookup and Lock privileges in order to access the folder containing a file you are trying to copy. In addition, any upper-level folders containing that folder must have Lookup access. If you need it, there is more information about setting folder privileges using OpenAFS.

Applications sometimes crash when you save or open files

If Unix symbolic links (symlinks) are used in a folder that you are accessing through AFS®, then some applications will crash when displaying an Open or Save dialog. Do not make symlinks. Remove the ones that are on the folders you access. Use the AFS® command fs mkmount instead of symlinks.

Text files don’t transfer correctly

When you move text files in AFS® between Unix and the Macintosh, you may run into formatting problems such as extra or missing carriage returns. To avoid this, use a “smart” text editor, such as BBEdit, on the receiving end. Such a program is able to decode the files as they are passed from one environment to another.

Your Web pages aren’t accessible

Make sure that you have set access privileges appropriately: Lookup access for your AFS® Home folder and Lookup, Read and Lock access for the www sub-folder. Appropriate access must be set for upper-level folders before any of the folders inside them can be accessed. In addition, make sure that each of the URLs is in the http format specified for a page in your www sub-folder, course locker or personal locker.

Managing folder access via the Terminal

NOTE: Before reading this section, be sure to read the introductory material on folders and tips on access privileges.
You can use OpenAFS to manage access to your folders. Alternatively, you can use the Terminal and AFS® commands to accomplish the same tasks, but with more difficulty. Here are the procedures:

AFS® Home folder access privileges

1. Open /Applications/Utilities/Terminal.
2. To see a listing of the privileges for your AFS® Home folder, type:
   fs la .
3. To allow anyone to look at the names of the folders and files in your AFS® Home folder, type:
   fs sa . system:anyuser l
   (NOTE: This line ends with the letter "ell," not the numeral "one.")

Sub-folder access privileges

The access options you choose for a sub-folder will depend on how you want its contents to be used. Here are three common examples:

Example 1. Web pages

If you have not already set up your www sub-folder in your AFS® Home folder, use the www setup tool. Login at https://sysnews.ncsu.edu/tools-bin/www-setup and follow the setup instructions. Copy your Web pages into the www folder. They must be stored there in order for you to provide URLs for them. If you need it, there is help with creating a new sub-folder.

1. Open /Applications/Utilities/Terminal.
2. Type:
   fs sa . /www system:anyuser rlk
   This will allow anyone to read the Web pages in your www subfolder but not to alter their contents.

Example 2. Read-only materials

In some situations you may want to allow a user to read a file (class notes, for instance) but not to make any changes. If you need it, there is help with creating a new sub-folder.

1. Open /Applications/Utilities/Terminal.
2. Type:
   fs sa . /folder unityuser rlk
   after you have replaced:
   folder with the name of the folder containing your read-only files
   unityuser with the name of the Unity user to whom you are granting read-only access.
3. Repeat step 3 for each additional user, if any, who is to have read-only access to the folder. To grant access privileges to a group of users simultaneously, see Creating and managing a group access list.

Example 3. Collaborative project

In some courses at NC State, you may be required to work on a group project. One person can store the project files in a folder on his/her AFS® space and grant every other group member appropriate privileges for that folder. If you need it, there is help with creating a new sub-folder.

1. Open /Applications/Utilities/Terminal.
2. Type:
   fs sa . /folder unityuser rlwik
   after you have replaced:
   folder with the name of the collaborative folder
   unityuser with the name of the Unity user to whom you are granting access.
   In this example the user has been given Lookup and Read privileges as well as Write and Insert. Depending on the type of project, Insert may or may not be appropriate.
3. Repeat step 3 for each additional user, if any, who is to have the same type of access to the project folder. To grant access privileges to a group of users simultaneously, see Creating and managing a group access list.

Changing or withdrawing access privileges

Changing privileges

1. Open /Applications/Utilities/Terminal.
2. To modify the level of access for an individual user for a certain sub-folder, type:
   fs sa . folder unityuserid access
   after you have replaced:
   folder with the name of the sub-folder
   unityuserid with the Unity ID of the individual
   access with the revised combination of privileges for that individual.

Withdrawing privileges

1. To withdraw an individual’s access privileges for a certain sub-folder, move to it by typing:
   cd  /folder
   where folder is the name of the sub-folder in question.
2. Withdraw the privileges by typing:
   fs sa . unityuser none
   where unityuser is the Unity ID of the individual.

Creating and managing a group access list

1. Open /Applications/Utilities/Terminal.
2. Change to the folder you created for the group. If you need it, there is help with creating a new sub-folder.
3. Type:
   pts creategroup unityid:group
   after you replace:
   unityid with your Unity ID
   group with the name you have chosen for the group. For example:
   pts creategroup jddoe:calcreview
4. To add a user to the group, type:
   pts adduser -user userid -group unityid:group
   after you replace:
   userid with the Unity ID of a group member
   unityid with your Unity ID
   the italicized group with the name of the group.
   Only one member is shown here, but you can enter all of group’s Unity IDs at the same time, separated by spaces. For example:
   pts adduser -user ptbar rzjon -group jddoe:calcreview
5. To assign privileges to the group, type:
   fs . sa unityid:group privileges
   after you replace:
   unityid with your Unity ID
   group with the group’s name
   privileges with the list of privileges for the group.
   For example:
   fs . sa jddoe:calcreview rlk

Kerberos tickets

There are several levels of security in Unity. To access a file in a Unity account, you must be granted a series of Kerberos credentials (tickets) and you must have AFS® folder access privileges. See “Showing Kerberos credentials” below to determine if you have each of these:

• A ticket-granting ticket (tgt) is acquired when you log in to OpenAFS and must be present before you can connect to any Unity server.
• A service-granting ticket (sgt) is acquired by using a tgt and must be available in order to actually use a server once you are connected to it. You will need a ticket for each server that you will be using. See “Showing Kerberos credentials” (below) for the three service-granting tickets you will need at NC State.
• An AFS® token is required during the volume-mounting process in order to access folders in Unity. See the information on using OpenAFS to set AFS® access privileges.

Showing Kerberos credentials

To see your Kerberos credentials,

1. Open your AFS® Home folder.
2. From /System/Library/CoreServices, run the Kerberos application.
3. Click on the small expansion triangle on the left side of the Ticket portion of the window to see the tickets that you have.
4. You should see several credentials. The first is a ticket-granting ticket, and the others are service-granting tickets.
   • If you have none, you are not logged in.
   • If you have only the first one, you are logged in to Kerberos but do not have the tickets you need to get AFS® tokens.
   • If you have any tickets whose names begin with the letters afs, but you still cannot access the server, contact the NC State Help Desk to report a server problem.

Showing AFS® tokens

To see your AFS tokens, run /Applications/afstokens. If you have any AFS® tokens but can’t access files in AFS® space, you may have a problem with access privileges. Contact the NC State Help Desk.

Go to the main page for this guide.

Last modified March 5, 2008 by cawalker