MacLeland 2.0 for OS X - ReadMe
June 2002


*** Contents ***
 Introduction
 New Features of Version 2.0
 Requirements
 Installation Instructions
 Help, Other Documentation, etc.
 Technical Details about the Installation

*** Introduction ***

MacLeland, a control panel for your Mac developed by Information Technology
Systems and Services (ITSS) at Stanford University, brings Kerberos
authentication and encryption to the Macintosh desktop for the SUNet community.
This means, for example, that Telnet sessions to host computers such as Elaine
can be encrypted, or that your password, which you would have entered in Eudora
to retrieve your mail from the Popserver, will not get transmitted unencrypted
across the network. This type of security is critical for many network services
available to the Stanford community.

MacLeland also provides access from the Mac desktop to Stanford's AFS file
system, meaning you can work with your AFS files like other Mac files on your
desktop. You also have access to the AFS files of other community members, as
well as to other public files.

This ReadMe file describes how to install MacLeland. For pointers to more
information about MacLeland, see "Help, Other Documentation, etc." at the end of
this document.


*** New Features of Version 2.0 ***                                                                  

MacLeland has been rewritten for the Macintosh OS X environment. Incorporating
and improving upon the open-source software OpenAFS, MacLeland lets you connect
to Stanford's AFS file system for direct, desktop access to your AFS home folder
(identified by your SUNet ID) or to other volumes and directories in Stanford's
AFS realm. The email proxy service has been improved to support multiple proxies
to multiple POP and IMAP servers.

The improvements in AFS access incorporate many changes; the way AFS works with
MacLeland 2.0 is very different from the way it worked with MacLeland 1.4. Be
sure to read the section on AFS (especially the comparison between the old and
new ways of working with it) in MacLeland's Help, available from the MacLeland
menu.

*** Requirements ***

To run MacLeland, your Macintosh needs the following:

- approximately 25 megabytes of free disk space (only 15 megabytes if you choose
not to install the OpenAFS module; see below).

- version 10.1.2, .3, .4 or .5 of the OS X operating system. If you are running
OS 8 or 9, you should install the previous version of MacLeland, version 1.4. If
you are running a later version of OS X, such as 10.2, this version of MacLeland
will not run. Check the ESS website (see below) to see if a newer version is
available.

- a network connection to the Internet or to SUNet directly (via modem)

In addition, you will need a SUNet ID to login to MacLeland. For information,
see the Web page "http://sunetid.stanford.edu".

Additionally, you will need the MacLeland program. MacLeland is part of the
Essential Stanford Software (ESS) collection of Macintosh programs for the
Stanford community. There are several ways to get a copy of MacLeland, along
with the other programs that are part of MacStanford, such as MacSamson,
Qualcomm's Eudora Pro and Netscape Communicator.

The easiest way is to download the software from the World Wide Web using a web
browser program like Netscape Communicator or Microsoft Internet Explorer. Look
for instructions on the ESS home page, "http://ess.stanford.edu". Other ways to
get the software are discussed there as well. 



*** Installation Instructions ***

IMPORTANT: This installer will install modified Kerberos components for use at
Stanford. If you reinstall or upgrade Mac OS X or Kerberos for Macintosh, you
may also need to run the MacLeland installer again.

You do not need to uninstall earlier versions of MacLeland to install the new
one. See the Help section on "Installing MacLeland" for information about the
usefulness of the old version and instructions for uninstalling it if you want
to.

Please follow all the instructions. In particular, be sure to restart your
Macintosh at the end of this procedure. 

1. If you downloaded the software from the ESS website and your web browser
handled it correctly, the downloaded ".gz" file will automatically be unstuffed
as a ".dmg" file. However, if you click on the download link and your browser
window fills with binary text (which probably looks like gibberish) then use the
browser's Save command to save the binary file on your hard disk, with the "save
as source" option. Then you must manually unstuff the saved file. Look for the
Stuffit Expander program on your Mac, and open the saved file with that program.
The file will then be unstuffed as a ".dmg" file. 

2. Double-click the ".dmg" file. Again, if your Macintosh is configured
normally, the file will be opened by the Disk Copy program, which mounts a
volume containing the MacLeland installer on your Mac's desktop. If, however,
the file opens in TextEdit, close the file, find the Disk Copy program (you
should have a copy of it in your Utilities folder), open the program by
double-clicking on it, and then drag the MacLeland ".dmg" file onto the Disk
Copy window, which will mount the volume containing the MacLeland installer.

3. Open the mounted volume, called MacLeland 2.0, by double-clicking on it.

4. Double-click the installer program and follow the directions. You will need
an Administrator account and password for the Mac. 

During the installation, you can choose between an Easy Install, a Custom
Install, or an Uninstall. Unless you are well aquainted with the individual
pieces of the MacLeland software, and know exactly why you would want to install
some and not others, we recommend you choose the Easy Install. With the Easy
Install, you will get the choice of installing the AFS components or not in a
special dialog box after the installation begins.

Choosing AFS: In general, we recommend Stanford users choose to install the AFS
components because of the additional functionality they provide, giving you easy
access to your Stanford AFS storage space from your desktop and from the
Terminal application. However, if you don't have a full-time Internet
connection, for instance, because you are using a portable Mac, or because you
are connecting to the Internet over a modem, you should be aware of problems
that can arise if you don't use the AFS feature carefully - that means,
generally, making sure you unmount any mounted AFS volumes before you disconnect
from the network or put your laptop to sleep. For more information, see the
section called "MacLeland and AFS" in the online help (look for the Help command
in the dropdown menu on the menu bar). In any case, if you install the AFS
components, you can easily disable them in the MacLeland control panel if you
later decide you don't want to use them.

5. At the end of the installation, you will be asked to restart your Macintosh.

6. After restarting, in the right side of the menu bar you will see MacLeland's
menu bar icon: a graphic depicting Hoover Tower and a building in the Quad. If
you click on that icon, you will see the MacLeland command menu. That indicates
the MacLeland installation was successful.

7. If you have any problems with the installation, check the "Installing
MacLeland" and "Troubleshooting" sections of MacLeland's help documentation.
Invoked with the Help command on the MacLeland menu, Help is set up as a web
browser document; when you select the command, MacLeland will open your web
browser, and open a browser window for MacLeland Help. You do not need to be
connected to the network to read the help.

8. To set up the email proxy so that you can use a Macintosh email program other
than Eudora to read your @Stanford email, see the instructions in the online
help (look for the Help command in the dropdown MacLeland menu on the menu bar)
for "MacLeland and email programs".  Please follow the directions carefully - it
is easy to configure this feature incorrectly.                                                


*** Help, Other Documentation, etc. ***

The Help command is available in the MacLeland menu.

More assistance, including updates and the latest news, is available on the
World Wide Web at this address: 

  http://macleland.stanford.edu/

In particular, the Web page has detailed information about "MacLeland, NNTP News
Server and non-Stanford IP Addresses". 

You may also find help by posting questions and looking for answers on the
su.computers.macleland bulletin board. For personal assistance, contact your
Local Network Administrator, Expert Partner or the cluster consultants. To
report problems, please use the HelpSU web page: http://helpsu.stanford.edu


*** Technical Details about the Installation ***

The following components are included in this release:

- MacLeland menu (for logging in and out of Kerberos)
- Mail proxy (POP and IMAP)
- S/Ident responder (e.g., used for WebAuth and cluster printing)
- Preference pane for configuring MacLeland options
- Kerberos status window

Optional installations:
- OpenAFS file system client (for mounting AFS volumes as folders on the
desktop)

This installer also updates the Kerberos for Macintosh libraries included with
Mac OS X and customizes them for the Stanford environment.

The MacLeland installer installs the following files.  These files are removed
on uninstall, except for those marked with an asterisk (*):

  /Library/MacLeland
  /Library/MacLeland/MacLeland Services.app
  /Library/MacLeland/MacLeland.menu
  /Library/MacLeland/Kerberos Status.app
  /Library/PreferencePanes/MacLeland.prefPane
  /Library/Authenticators/MacLeland.loginAuthenticator
  /Library/Preferences/edu.mit.Kerberos (*)

The installer makes changes to the following files, which are reverted on
uninstall:

  /Library/Preferences/loginwindow.plist

The installer also updates the system Kerberos framework to version 4.0 of
Kerberos for Macintosh, customized for the Stanford environment. These changes
are not reverted if you uninstall MacLeland.  Files updated include:

  /System/Library/Frameworks/Kerberos.framework
  /System/Library/CFMSupport/Kerberos.bridge
  /System/Library/CFMSupport/Kerberos Support.bridge

Installing the OpenAFS package installs files into the following locations:

  /Library/OpenAFS/
  /Library/StartupItems/OpenAFS/
  /Library/Contextual Menu Items/AFSCMPlugin.plugin
  /private/var/db/openafs/etc/
  /private/var/db/openafs/cache/

These files are removed when MacLeland is uninstalled, except for OpenAFS cache
files, which may remain on the hard drive.