Using MacLeland with the AFS File System

If you have file space in AFS, you can use MacLeland to access your AFS files, as well as AFS files belonging to others. (Access controls set by the owner may limit or prevent your access to their files, of course.) This can be done by mounting the appropriate AFS volume on your desktop, to use similarly to the way you would work with other Mac folders, or by connecting to the directory through the Terminal program. Both of these methods are discussed below.

Remember, you must have the MacLeland OpenAFS program installed - it is a separate installation from MacLeland in versions 2.0 and higher. See the Installing MacLeland section for more information.

Note well: the AFS features in MacLeland 2.0 and above are very different from their counterparts in earlier versions. Generally speaking, AFS previously worked poorly with pre-2.0 MacLeland; it works very well with MacLeland now, and most MacLeland users should learn about it and consider using it for a variety of reasons. A comparison highlighting the improvements appears later in this section.

This section also includes cautionary information about using AFS on Macintoshes that are not always connected to the Internet.

AFS on the Desktop

To mount an AFS volume on your desktop, use either the Mount Home Folder or the Mount Other... command, found in the MacLeland menu. If the commands are grayed out but the command below them, Start AFS Service, is not, click on that command - that can establish AFS service if it did not get started properly at Mac bootup, or if a loss of network connection (or some other cause) caused MacLeland to think AFS was not available. (The Start AFS Service command does require you to enter an administrator password, however.)

Once it is mounted, you can see the volume's contents by double-clicking on it to open a Finder window for it, or by using an open Finder window to navigate to it. The Finder will show all files and directories in the volume, except for dotfiles (files whose names begin with a period, e.g., .login), which are thus not accessible from the desktop. (You can work with them through the Terminal application - see below.) For other files, you can drag/drop them to your other volumes (your startup drive, for instance), and drag/drop files from them to your mounted AFS volume. You'll also have access to them in Open and Save dialog boxes.

This means, for instance, that you can use your AFS file space as another volume where you can save your Macintosh files, e.g., to back them up, or to make them available for sharing with others. If you create web pages, for instance, you will find it simple to create them on your Macintosh and then drag the HTML files into your WWW folder in your AFS home folder - and voila, the web pages are available on the web. (For directions on setting up your WWW folder in AFS, choose the appropriate link on the Stanford Web Service page.)

Important: For several different reasons, we generally recommend that when you want to work with a file stored in AFS space, you first copy it to your Mac's hard drive, and then open it, work with it, save it back to your Mac, and then copy it back into AFS. In most cases, this is not a requirement, and you may find you can work directly with the AFS version of the file without problem. However, with some applications in OS X.3 - SubEthaEdit always, and in some (fortunately) rare cases, Microsoft Word - working with an AFS file directly can cause a kernel panic in OS X, meaning that the machine must be rebooted, a quite dire failure. The problem is being investigated by programmers in the OpenAFS community. In the meantime, consider yourself warned.

Sharing Files in AFS Using MacLeland

Using MacLeland and AFS to share files with others is simple, though not quite as intuitive as a Mac user might expect. The easiest way is to mount the AFS volume, save the file on the volume, and then use the Access Control List... command (found in the volume's or folder's contextual menu) to set the appropriate permissions. The other person or people can then mount the same volume and access the file. (See the example below.) Other differences you might encounter (they're mostly minor and obscure) are also described below.

Example: You are creating a Microsoft Excel spreadsheet you want to share with Alma, who will work on it too. Another person on the team, Bryant, will want to see it occasionally as well. You might consider emailing it back and forth, but in this case, you choose to save it in your AFS space, and allow Alma and Bryant to use it from there on their Macs. (You could consider making it available on the web, but that probably means Alma won't be able to work on it.)

After mounting your home folder (with MacLeland's Mount Home Folder command), you create a new folder called, say, classproject. Move your spreadsheet file into that folder. The next step is to set the appropriate permissions (or, as they're called in AFS, the ACLs, pronounced "ackles"). You set the permissions for the enclosing folder or volume, not the individual file - that's why you created the classproject folder to hold your spreadsheet file. To set the ACLs appropriately, hold down the Control key, and click-hold on the classproject folder. You'll see the contextual menu for the folder, which includes the AFS submenu. Open the submenu to see your AFS options:

Select the Access Control List command (the other commands are discussed later, below):

The current list of permissions is shown; the permissions may be given for an individual user (such as jdoe, the owner in the example) or for AFS groups, signalled by the colon in the name, which separates the owner ("system" in the examples) from the group's name.

The permissions for each person or group are shown in the Permissions column, as a string of letters, abbreviations for the 7 different types of permission (rlidwka, shown above, represents all 7; l, for list, only one). Additionally, some commonly used combinations have their own names, such as Read, shown above with its combination, rl (for read and list).

For the example, you would want to add permissions for Alma and Bryant. To add to the list, click the Add... button, and this dialog box will appear:

First, you enter the SUNet ID of the person, or the group name of the group, to whom you want to grant (or deny) the permission. You can specify only one person or one group. Choose Normal (to add permissions) or Negative (to remove permissions for someone who would otherwise have rights due to an entry in the Normal list, e.g., to deny privileges to an individual who is in a group that appears in the Normal list).

For permissions, you can either set the 7 individual permission types by clicking the check boxes, or choose one of the combinations from the dropdown menu (which will reset the 7 check boxes as appropriate). In general, unless you are well-versed in ACLs, you will probably find the combinations (None, Read, Write, and All) to be adequate for your needs. See Setting Permissions for more information about AFS permissions.

For Alma, who gets to update the file, you would probably choose Write permission from the drop-down menu (which sets rlidwk). For Bryant, who needs only to see the file, you would probably choose Read from the menu (which sets rl). Click Save to save the permissions you set for each person, and return to the updated Access Control List window.

To change the permissions for a person or group already in the Normal or Negative permissions list, select the person or group and then click the Edit... button (or simply double-click on the person or group). Change the settings as appropriate, Save, and then see your changes reflected in the Access Control List window.

Some important details about ACLs:

• changing the permissions for a folder with this method does not change the permissions for existing subfolders of the folder. You will need to follow the same procedure above for each subfolder of the folder you want to give people access to. Alternatively, you can issue the UNIX AFS command fsr setacl from a login to Cardinal or another Leland systems host to set the ACLs recursively for all the subfolders of the folder. (The Terminal program does not recognize the fsr setacl command.)
• Newly created subfolders will inherit the ACL of the parent folder at the time the subfolder is created.
• If you give someone access to a subfolder, that person must have at least "l" (list) access to all the containing folders (which mainly gives the user the ability to see the names of files within the folder) or else the subfolder will be basically inaccessible to that person. This is taken care of in our example because by default, and as you can see, the group system:anyuser (a group that includes any user of AFS) has list access to the folder. However, since you could take that access away from system:anyuser if you want, you should know when it is necessary.
• Further information about ACLs, including how to set up and use groups, appears in the AFS at Stanford web site. You can use the Terminal application to issue AFS commands that match and expand the capabilities described above.

Volume Information, Flush Directory, Flush Volume

The other three commands in the AFS submenu of the contextual menu are:

Volume Information...

Use this command to see how much AFS space you have been assigned (your quota) and how much you are using.

Flush Directory and Flush Volume

Use this command to refresh the list of files and folders in the selected folder/directory or the entire volume. This is seldom needed, but occasionally, the window can get out of synch with the actual contents of the AFS directory. If, for instance, you are looking at an open Finder window for the AFS volume and someone tells you that a file has just been added to that directory, then if you don't see it appear, you might want to try one of these commands.

Differences and Improvements from Earlier Versions of MacLeland

MacLeland has always supported AFS access, but generally not well. Few people used it because of its problems, despite its significant benefits, particularly for web work. Here are some notes about its improved functionality for MacLeland 2.0 and above.

• Access to AFS is provided through OpenAFS software, which has been developed for many different platforms and is more stable and easier to support than the Netatalk software running on servers that supported the previous version.
  
• Netatalk requires a connection through AppleTalk; OpenAFS supports an IP connection, meaning you can access your Stanford AFS volumes from anywhere with an Internet connection.
  
• OpenAFS does not support directly mounting a subdirectory of a volume, the way MacLeland 1.4 and earlier did. For instance, in the older version, you could mount a department's web space by selecting the Mount Other command, choosing the "dept" option, and then typing "economics/WWW" rather than simply typing "economics" and then opening the WWW folder inside once the "economics" folder opens. In the new version, you'll have to do the latter, though for frequently used subdirectories, aliases can help get you to your destination faster (see below).
  
• You can create an alias for a mounted AFS volume, or for a folder or file within it, which you can put wherever you like on your Macintosh, such as in your Favorites folder. Alas, aliases can't be used to mount folders that aren't mounted. An alias will work, however, as a shortcut to the volume or folder or file if you remount the volume first. This is an improvement over earlier versions of MacLeland, where an alias worked only until the volume was next unmounted and not after subsequent remounts.
  
• The older versions of MacLeland did not support ACL-setting from Mac OS 8.5 on. In MacLeland 2.0 and above, basic ACL-setting is supported from the desktop, as described above, while all functionality is supported through the Terminal application (see below).
  
• File names were restricted to 31 characters in earlier versions of the Mac OS, causing problems when copying UNIX files (whose names can be longer) from AFS to the Mac. This is not a problem with Mac's OS X, since it supports UNIX names, mostly...
  
• OS X, like earlier versions of the Macintosh OS, forbids colons from filenames created in the Finder. When an AFS volume is mounted on the desktop with MacLeland, colons in the names of existing AFS files (abc:def) appear as forward-slashes (abc/def) though internally, they remain colons. In earlier versions of MacLeland, colons in a name could prevent the file from being copied or otherwise used on the Macintosh.
  
• Macintosh files are stored in AFS by splitting the data and resource forks of the file. The data fork is stored under the given file name; the resource fork gets stored separately. In the older versions of MacLeland, the resource fork was saved in a separate hidden subfolder within the folder where the data fork was saved, a subfolder called ".AppleDouble". This caused many problems, especially involving ACLs for the hidden folder. In MacLeland 2.1, the resource fork is saved in the same folder as the data fork, with the same name, but preceded by "._" (period and underscore), making it a hidden file. This has potential for problems too, but in general is a cleaner solution to the situation than the AppleDouble one provided. The key factor to know is that if you work with your Mac files stored in AFS only via the Desktop, you will not have problems with this implementation; that was not the case with the older version of MacLeland.

Using AFS in the Terminal Program

Mounted AFS volumes are also available to the Terminal program, which thus supports the full range of AFS commands and features. Terminal, a Mac OS X application that Apple provides in the Utilities folder of the Applications folder, its primary use is to provide a command-line interface to the UNIX underbelly of OS X. But once an AFS volume is mounted through either of MacLeland's two Mount commands, you can begin working with it (and its files and directories) through Terminal as well as issue other AFS commands

The best way to reference AFS files is through the path established through the desktop, in particular, through the /Network top-level directory. So, for instance, if you are jdoe and have your AFS home directory mounted on your desktop, you could change to its directory (cd) with this command from Terminal:

[macdoe:~] jdoe% cd /Volumes/jdoe
[macdoe:/Volumes/jdoe] jdoe%

An excellent shortcut is available: you can enter an entire pathname by dragging the volume, folder or file from the desktop or Finder window into the Terminal window. For example, jdoe could first type the cd command, and then, on the desktop, drag the jdoe AFS volume icon into the Terminal window. The path "/Volumes/jdoe" would get added to the command line, just as it was typed in the example above. (This shortcut works for any file on the Mac, whether it's in AFS or stored on one of the Mac's hard drives, making it a handy way to find the path for any given item appearing in the Finder.)

Once you have issued a command such as the above example shows, you are working with AFS. You can issue all the various fs and pts commands, but only to the extent that they work with directories and files within the mounted AFS volumes; you cannot work with AFS directories and files outside the mounted volumes. Mounting the AFS root volume (you can find it as one of the menu items in the Mount Other... dialog box) will give you the ability to reach any AFS file. (But see the important caveat below before mounting that volume.)

Because AFS-on-the-desktop supports access to most of the files in the directory and the ability to grant and revoke privileges to users and groups, it will suffice for most basic AFS needs of the average Mac/AFS user. But the Terminal method also provides at least two important capabilities unavailable directly from the desktop:

• access to see, examine, modify and delete the hidden dotfiles (e.g., .login)
• ability to create, modify, and delete groups, through the pts command (see AFS at Stanford for details)

Cautions and Tips for Using AFS Without a Full-time Connection to the Internet

If you have a portable Macintosh or if you use a modem to connect your Mac to the Internet - in other words, if you don't have a full-time connection to the Internet - you can use AFS, but you must be especially cautious, since disconnecting from the network with AFS volumes mounted can create problems, as described below. Here are some warnings and tips for you:

1. Don't turn on the "Globally mount AFS root filesystem" or "Automatically mount home folder after MacLeland login" settings in the AFS panel of the MacLeland settings. These settings are designed for desktops that have a persistent network connection. Using these features on a portable may cause problems if and when the system is put in Sleep mode and/or moved across subnets (via AirPort connections). The manifestation of the problem is that you may see the spinning beach ball for an extended period of time. You can try and restart Finder, but this is not always successful. You generally can resolve the problem by logging out from your Mac (not just from MacLeland) and logging back in again. If you let the spinning beach ball go on long enough it MAY actually resolve the location problems but not reliably.

2. As mentioned earlier, if you find the Mount commands grayed out, click on the Start AFS Service command below them - that will re-invoke the startup process for AFS. Note that this requires you to enter an administrator password, which is required by the underlying process.

3. Don't put the system to sleep with AFS volumes mounted, especially with open files on those mounted volumes. It's always a good practice to close open files before putting a laptop to sleep anyway, if you open them through AFS rather than by copying them to your Mac first. If you violate this rule, you may get an error regarding the volume no longer being available when you wake the system. If you move across subnets, you will need to renew your login to MacLeland when you wake the system. Problems that can arise include losing any changes since the last save of any AFS file that was open when you put the Mac to sleep. Some applications will create backups in case of some loss of system fidelity, but not all do.

If you do not have open files but do have mounted AFS volumes when you put your Macintosh to sleep, then when you wake the system, immediately try MacLeland's Renew Login command, which usually resolves any problems.