Current as of KfM 4.0.3
Kerberos for Macintosh (KfM) 4.0.3 for Mac OS X provides Kerberos 4, KClient, Kerberos 5 and GSS implementations together in one unified package, with support for the various Mac OS X runtime environments. Kerberos for Macintosh 4.0.3 for Mac OS X consists of the Kerberos framework, CFM compatibility libraries, the Kerberos management application, the Kerberos Login Authenticator, basic command-line utilities, /usr/lib and /usr/include support. Also included is a preference file preconfigured for MIT.
The KfM 4.0.3 OS X installer installs all these components to the correct location on a Mac OS X volume while removing older and out-of-date KfM components. Since the components are installed at the system level, once they are installed by one user, KfM will be available to all users on the computer.
If you have any questions or comments, please send them to <krbdev@mit.edu> .
The minimum system required for the components installed is Mac OS X 10.1.2. Only Power Macintosh machines are supported.
There is a separate installer for KfM 4.0 for Mac OS 8 & 9.
The Kerberos for Macintosh 4.0.3 OS X installer as distributed from MIT was built with Mindvision VISE 7.3. While this installer should build without problems in later versions of VISE, we have not tested it.
If you are working from the KfM installer source distribution, you should copy the KfM 4.0.3 Mac OS X binaries from the standard KfM 4.0.3 distribution (which you can download here) into the "Put Binaries Here" folder.
Specifically, copy the contents of
Kerberos for Mac 4.0.3:Binaries:Mac OS X:from the KfM distribution into the "Put Binaires Here" folder of the installer source distribution.The installer should automatically find the binaries once they are copied as described above. Then you can replace or add localized components as necessary.
Only an Easy Install option is available. Uninstall is also available, but this is not strictly a package.
Easy Install installs the Kerberos management application (a bundled Mach-O application), Kerberos.framework, Kerberos.bridge, Kerberos Support.bridge, Kerberos.loginAuthenticator, command-line utilities, /usr/include files, /usr/lib files, and edu.mit.Kerberos (the Kerberos preferences file) - see below for locations. The installer also installs a version of tar for temporary use by the installer, but this is deleted at the end of the install.
The installer will force a restart at the end of an install, and will try to quit all applications and force a restart at the end of an uninstall.
There are two build targets in the KfM 4.0.3 OS X installer - "Default Target" and "KfM 4.0 Silent". The only difference between the two is that "Default Target" will ask you for the name and location of the installer to be built (and you can choose whether to build a debug installer), whereas "KfM 4.0 Silent" will just build a default-named non-debug installer in the same directory as the .vct file.
You should build this installer as a "Carbon" installer. It is meant to run under Mac OS X only, and thus you should not build a "Classic" version of it.
The Kerberos for Macintosh OS X installer has a variety of special features that you should be aware of before looking at or modifying the installer archive.
Custom Install Locations
One major design issue was that the KfM installer needs to install and uninstall files from Mac OS X directories that are not part of VISE's standard install locations (because they are not locatable by using FindFolder), such as the
/usrdirectory and many of the/Systemlocations. So we've created a set of custom install locations, which are built as an external code resource using C in CodeWarrior. The custom locations are compiled as a plug-in that is placed in the VISE application's folder.Fortunately once specified in the installer archive, the custom install locations "stick" in the installer archive and work without the plug-in being present, so in theory you shouldn't need the plug-in. In practice and for best results, however, you should copy the file
ExternalCodeResources:KfMLocations:KfM Locationsfrom the installer source distribution to the "Install Locations" subfolder of your VISE application's folder before making any changes to the installer.The custom install locations are:
Temporary/Old KfM Files
/System/Library/Authenticators
/System/Library/CFMSupport
/System/Library/Frameworks
/Library/Preferences
/Library/Receipts
/usr
/usr/bin
/usr/include
/usr/lib
/private/var/root/.TrashThe "Temporary/Old KfM Files" location is special - the code first creates an "Old Kerberos for Mac Files" directory in the
/tmpdirectory if one doesn't exist, and then tells VISE how to find that directory.
/Library/Receiptslocation is not currently used, because you can't use custom install locations in the Installer Log location pop-up.From now on this document will refer to these locations without necessarily specifying that they are custom locations; basically any location that looks like a Unix path is a custom location.
Tarred Files
Some of the files in the KfM OS X installer are .tar files that are installed and then untarred by calling a shell script compiled into a external code resource (see the VISE manual for more information about this). These shell scripts refer to a binary called "kfmtar", which is a renamed version of gnutar installed by the KfM OS X installer.
We are installing the Kerberos.framework and /usr/include header files as Tar files to work around a bug in VISE 7.3. The bug is: VISE cannot properly re-create UNIX symlink files on Mac OS X disks formatted with UFS. This is an important issue because both the Kerberos.framework and /usr/include headers have symlinks. Stuffit Expander does not properly re-create the symlinks either, and our build system generated Tar files anyway, so it was simpler to use Tar files and untar them to work around this issue.
However, the tar that ships with Mac OS X cannot handle the very long pathnames used in Kerberos.framework, so we create the Tar file with gnutar. But gnutar is only installed on Mac OS X if the user has also installed the Developer Tools, which many users won't have done. So the installer installs a copy of gnutar - renamed to kfmtar to avoid possible conflicts - into the Temporary Items folder (on Mac OS X, this is in the /tmp directory), uses it to untar the two Tar files installed, and then deletes 'kfmtar' at the end of the install.
See the Shell Script Resources section at the bottom of this document for more information about the external shell script resources.
Uninstall Action Items
Most of the action items in the KfM Mac OS X installer are set to run on both install and uninstall (this is in contrast to the KfM installer for Classic Mac OS, which has its own special set of action items for uninstall). The action items serve a dual purpose - they move existing copies of KfM components out of the way at install time, and simply remove them at uninstall time. If you modify the installer to install additional files, be sure to add similar action items that run at uninstall time to remove them.
In the table below, actual files and folders are displayed in bold, whereas action items names are displayed in italics. Each action item has a definition of what it does, and then an explanation of why it does this.
Items are listed in the order in which they appear in the .vct. Some may be inside placeholder folders for organizational purposes; this list is equivalent to the order of items if the hierarchy was flattened.
Note that on Mac OS X, the "Domain" part of the location is important - it can mean the difference between installing a file in the System, where all users can access it, and installing it in just the current User's directory.
Some of the Gestalts used are not part of the VISE default Gestalts - they are custom Gestalt checks which are included in the .vct file (you can easily create and edit the Gestalts in VISE using the Archive->Gestalts menu item).
| Files | Install To: | Replace | Gestalts |
|
Message Action Item:"Requires Mac OS X 10.1.2" If the installer is run on an OS less than Mac OS X 10.1.2 (a check made using the custom Gestalt), a warning message that the installer will only work on 10.1.2 and greater is displayed. KfM 4.0 final requires Mac OS X 10.1.2 or later 10.1 version to work properly. We're doing this instead of using the built-in system version check of VISE because the message VISE displays would say "This installer requires System 10.1.2 or greater," which is not the correct way to describe the system. Unfortunately using an action item means this message won't come up until the user actually clicks on the "Install" button. Only runs on installs. |
n/a | n/a | Less Than Mac OS X 10.1.2 |
|
Stop Action Item: Stop if not Mac OS X 10.1.2 If the installer is run on an OS less than Mac OS X 10.1.2 (a check made using the custom Gestalt), this action item brings the installation to a halt before it can begin (the user is warned of this by the above action item). Only runs on installs. |
n/a | n/a | Less Than Mac OS X 10.1.2 |
|
Message Action Item: Message OS X Too New If the installer is run on an OS whose version is Mac OS X 10.2 or greater (a check made using the custom Gestalt), a warning message that KfM is not supported on this version of Mac OS X and thus the installer will not continue is displayed. Mac OS X 10.2 contains a newer and significantly different version of KfM, and thus KfM 4.0.x should not be installed on it because it will not work properly, and we do not want to replace the new version of KfM with KfM 4.0.x. Only runs on installs. |
n/a | n/a | GT or Equal Mac OS X 10.2 |
|
Stop Action Item: Stop if not Mac OS X 10.1.2 If the installer is run on an OS whose version is Mac OS X 10.2 or greater (a check made using the custom Gestalt), this action item brings the installation to a halt before it can begin. See the preceding message action item for an explanation of why we do this. Only runs on installs. |
n/a | n/a | GT or Equal Mac OS X 10.2 |
|
Message Action Item: Message "Uninstall Warning" This message warns the user that an uninstall on OS X will remove the parts of Kerberos that ship with Mac OS X 10.1.x, and provides the user with an opportunity to cancel the install if they want. If the user clicks on Cancel, the uninstall stops. Only runs on uninstalls. |
n/a | n/a | |
|
kfmtar A renamed copy of the gnutar distributed with the Mac OS X Developer Tools. Used to untar the Kerberos.framework and /usr/include headers. The tar that ships with Mac OS X cannot handle the very long pathnames used in Kerberos.framework, so we create the Tar file with gnutar. But gnutar is only installed on Mac OS X if the user has also installed the Developer Tools, which many users won't have done. So we install our own copy of gnutar - renamed to avoid possible conflicts and then delete it at the end of the install. See Tarred Files notes above. |
Temporary Items, System Domain | Always | |
|
Library (folder) This folder matches |
Root of Startup Drive, System Domain | Never | |
|
Receipts (folder) This folder matches The installer log is placed here. See notes for the Library folder above. |
Other... (Library) | Never | |
| Authenticator Items (place holder folder - not installed) | n/a | n/a | |
|
Move Action Item: Move Kerberos auth to OldKfM Looks for a folder named "Kerberos.loginAuthenticator" in Runs on install and uninstall. |
n/a | Always | |
|
Kerberos.loginAuthenticator (folder & contents) The Kerberos login authenticator bundle. |
/System/Library/Authenticators, System Domain | Always | |
| CFMSupport Items (place holder folder - not installed) | n/a | n/a | |
|
Move Action Item: Move Kerberos.bridge to OldKfM Moves any files in Moving old (and possibly out of date) "Kerberos.bridge" files out of the way. Runs on install and uninstall. |
n/a | Always | |
|
Move Action Item: Move KerbSppt.bridge to OldKfM Moves any files in Moving old (and possibly out of date) "Kerberos Support.bridge" files out of the way. Runs on install and uninstall. |
n/a | Always | |
| Kerberos Support.bridge | /System/Library/CFMSupport, System Domain | Always | |
|
Kerberos Support.debug.bridge This item may not be found in all versions of the installer, especially those meant for final releases. |
System/Library/CFMSupport, System Domain | Always | |
| Kerberos.bridge | /System/Library/CFMSupport, System Domain | Always | |
|
Kerberos.debug.bridge This item may not be found in all versions of the installer, especially those meant for final releases. |
System/Library/CFMSupport, System Domain | Always | |
| Framework Items (place holder folder - not installed) | n/a | n/a | |
|
Move action item: Move Kerberos.frame to OldKfM Looks for a folder named "Kerberos.framework" in Runs on install and uninstall. |
n/a | Always | |
|
Kerberos.framework.tar The tar file of the Kerberos.framework. Set to call the "untar Kerberos.framework" external shell script resource after installation to untar it. See Tarred Files and Shell Script Resources for more information. |
/System/Library/Frameworks, System Domain | Always | |
| Preferences Items (place holder folder - not installed) | n/a | n/a | |
|
Move Action Item: Mv Kerberos Prefs to /Lib/Prefs Searches the system preferences folder This takes an existing old-style-named preferences file from the old location (this name and location were used by KfM 4.0a17 and earlier) and moves it to the current preferences location in preparation for being renamed. Runs only on installs. |
n/a | If Newer Modification Date | |
|
Rename Action Item: Rnm KerberosPrefs to edu.mit.Ke Searches Because the action item is set to "Never replace", it will only rename the file if there isn't already a file named "edu.mit.Kerberos" in the directory (we don't want to replace a current prefs file with an older one). Runs only on installs. |
n/a | Never | |
|
Move Action Item: Move Kerberos Prefs to OldKfM Searches This is to remove any old prefs files that were not renamed by the previous action item because there was already an existing preferences file with the correct name. Runs only on installs. |
n/a | If Newer Modification Date | |
|
edu.mit.Kerberos Don't replace existing prefs files which are probably valid (this includes an old one that may have been moved and renamed by the previous action items). Preferences Folder, Local Domain is equal to |
Preferences Folder, Local Domain | Never | |
|
Applications Items (placeholder folder - not installed) |
n/a | n/a | |
|
Move Action Item: Move Kerberos.CB to OldKfM Searches Applications, System Domain ( This item removes an out-of-date and incorrectly named CFM Carbon version of the Kerberos management application, which has been superseded by the Mach-O version. Runs only on installs. |
n/a | Always | |
|
Move Action Item: Move Kerberos.CB.dbg to OldKfM Searches Applications, System Domain ( This item removes an out-of-date and incorrectly named CFM Carbon debugging version of the Kerberos management application, which has been superseded by the Mach-O version. Runs only on installs. |
n/a | Always | |
|
Move Action Item: Move Kerberos to OldKfM Searches Applications, System Domain ( This item removes the out-of-date CFM Carbon debugging version of the Kerberos management application, which has been superseded by the Mach-O version. Runs only on installs. |
n/a | Always | |
|
Move Action Item: Move Kerberos.debug to OldKfM Searches Applications, System Domain ( This item removes the out-of-date CFM Carbon debugging version of the Kerberos management application, which has been superseded by the Mach-O version. Runs only on installs. |
n/a | Always | |
|
Move Action Item: Move Kerberos.app to OldKfM Searches Applications, System Domain ( This item removes possibly out-of-date versions of the Mach-O Kerberos management application. Runs on installs and uninstalls. |
n/a | Always | |
|
Move Action Item: Move Kerberos.debug.app to OldK Searches Applications, System Domain ( This item removes possibly out-of-date debugging versions of the Mach-O Kerberos management application. Runs on both install and uninstalls. |
n/a | Always | |
|
Kerberos.app A bundled application (the .app won't show up in the Mac OS X finder), the Mach-O Kerberos management application. |
Applications, System Domain | Always | |
|
Kerberos.debug.app A bundled application (the App won't show up in the Mac OS X finder), a debugging version of the Mach-O Kerberos management application. This item may not be found in all versions of the installer, especially those meant for final releases. |
Applications, System Domain | Always | |
| /usr/bin Items (place holder folder - not installed) | n/a | n/a | |
|
Move Action Item: Move kdestroy to OldKfM (4 separate action items) All these action items search These action items remove possibly out-of-date versions of these files. All these action items run on both install and uninstall. |
n/a | Always | |
|
kdestory (4 separate files) The basic UNIX command-line utilities. |
/usr/bin, System Domain | Always | |
|
Find Action Item: Find /usr/include Searches the Runs on both install and uninstall. |
n/a | n/a | |
|
Jump Action Item: Jump To /usr/lib items If the previous action item does not find a Likewise, we do this check on uninstall because attempting to uninstall items from a nonexistent folder would result in the installer giving an error. Runs on both install and uninstall. |
n/a | n/a | |
| /usr/include Items (place holder folder - not installed) | n/a | n/a | |
|
Move action item: Move Kerberos headers to OldKfM (9 separate action items) All these action items search These action items remove possibly out-of-date versions of these files. All these action items run on both install and uninstall. |
n/a | Always | |
|
includes.tar The tar file of the Kerberos /usr/include headers. Set to call the "untar Kerberos includes" external shell script resource after installation to untar it. . See Tarred Files and Shell Script Resources for more information. |
/usr/include , System Domain | Always | |
| /usr/lib Items (place holder folder - not installed) | n/a | n/a | |
|
Move action item: Move libcom_err.dylib to OldKfM (7 separate action items) All these action items search Note: libdes524.dylib is not a file that is installed by KfM 4.0 final.
This is an incorrectly named library from the developmental releases of
KfM 4.0 that we need to remove. These action items remove possibly out-of-date versions of these files. All these action items run on both install and uninstall.
|
n/a | Always | |
|
libcom_err.dylib (6 separate files) The UNIX compatibility libraries. |
/usr/lib , System Domain | Always | |
|
Move Action Item: Move Old KfM Files to Trash 1 Searches the Temporary Items directory for an "Old Kerberos for
Mac Files" folder (created by the custom install location code when
it's first used) and moves it to Since the installer is running as the administrative user, the "Trash"
is The files are moved to root's Trash instead of the user's Trash for two reasons: (1) the installer is running as an administrative user (hence, root) and so VISE considers root to be the current user; and (2) some of the files we are removing - such as the Kerberos.framework - are owned by root. If we put them in the user's Trash, the user won't be able to delete them. Since VISE currently has no facility for changing file permissions of already-installed files, we put files into the root's Trash instead. We could have deleted all the old KfM files outright instead of moving them around, but we thought providing a backup of the original files, even though they are mostly inaccessible to the average user, was better. Runs on both install and uninstall. |
n/a | Always | |
|
Delete Action Item: Delete old Old KfM Files folder If the "Move Old KfM Files to Trash 1" action item failed,
searches If "Move Old KfM Files to Trash 1" failed, it's because there's
already an "Old Kerberos for Mac Files" in We don't just want to rename the older folder of files, because then every time a user runs the installer more files appear in root's Trash, which the user probably won't empty... so old copies of KfM could eventually fill the hard disk! So we delete it outright. We only keep the last set of old KfM files. Runs on both install and uninstall. |
n/a | n/a | |
|
Move Action Item: Move Old KfM Files to Trash 2 If the "Move Old KfM Files to Trash 1" action item failed,
searches Temporary Items for an "Old Kerberos for Mac Files"
folder (created by the custom install location code when it's first used)
and moves it to |
n/a | Always | |
|
Delete Action Item: Delete kfmtar Searches the "Temporary Items" directory for a file named "kfmtar" (installed at the beginning of the install) and deletes it. kfmtar, as explained in Tarred Files above, is only for temporary use by the installer, so we clean up afterwards. Runs only on install. |
n/a | n/a | |
|
Message Action Item: Message "Restart Uninstall" This action item shows a dialog warning the user that the installer is going to restart when an uninstall finishes. There is no option to cancel the restart, because leaving some Kerberos stuff running in memory after removing it would be bad. The action item is set to call the external code resource "Restart" after the message is displayed, since VISE does not actually provide a built-in way to force a Restart after an uninstall. Only runs on uninstalls. |
n/a | n/a | |
|
Message Action Item: Message "Restart Install" This action item shows a dialog warning the user that the installer is going to restart when an install finishes. There is no option to cancel the restart, because we want to force memory resident processes of KfM to quit since in case we've just installed a newer version. We need this action item for two reasones: (1) to call the "Restart" external code resource, and (2) because in the installer settings we have told VISE to suppress "success" dialogs in order to suppress an excess message during uninstall, and it turns out that the standard VISE restart warning is considered a "success" dialog, and is suppressed as well. Since it's kind of alarming for the installer to restart without any warning when it's done, this message action item simply emulates the original VISE behavior. The action item is set to call the external code resource"Restart" after the message is displayed, since the VISE Restart functionality under Mac OS X is unreliable. Only runs on installs. |
n/a | n/a | |
Special Installer Settings
There are a few settings of special note in the "Installer Settings" of the Kerberos for Macintosh OS X installer:
Require OS X Authentication (Attributes tab) - Since the installer installs files in directories owned by root, the installer must have administrator access. This option is checked so that the installer will prompt for an administrator password when it starts up. The install will not continue if a password isn't entered. The installer would fail when attempting to install some files if this option was unchecked.
Allow Installs to Non-HFS volumes (Behavior tab) - This option must be checked in order to allow installs to UFS formatted volumes. (This option is only in VISE 7.3 and earlier - VISE 7.4 does not provide a way to prevent installs to non-HFS volumes.)
Install Log File Location (Extras tab) - By default VISE will place the install log on the root level of the drive (that is, the
/directory). We regarded that as undesirable. So instead we put the install log in the/Library/Receiptsdirectory, which is where other system stuff puts install logs.Installation Location of "edu.mit.Kerberos" File
The edu.mit.Kerberos preferences file may be found in two locations on a Mac OS X volume, the system preferences in
/Library/Preferencesand the user preferences in/User/userid/Library/Preferences. The KfM installer installs the edu.mit.Kerberos file in the system location so that it is accessible by all users of a Mac OS X machine, and you should do the same. See the Kerberos Preferences on Mac OS X Documentation for a full explanation.Uninstall
Uninstall support has been built into the installer. Files that will be uninstalled are: the Kerberos management application (both debug and non-debug), Kerberos.framework, Kerberos.bridge (both debug and non-debug), Kerberos Support.bridge (both debug and non-debug), Kerberos.loginAuthenticator, /usr/bin Kerberos command-line utilities, /usr/include Kerberos headers, /usr/lib Kerberos libraries, and edu.mit.Kerberos (in /Library/Preferences, does not remove the copy in the user's home directory).
Instead of using the VISE built-in uninstall feature, the KfM OS X installer uses a bunch of action items that move the files to an "Old Kerberos for Macintosh Files" folder in the Trash (these are the same action items used to move existing files out of the way when an install is done), and then a special external code resource to force a restart afterwards.
We don't use the built-in uninstall feature because it attempts to delete items outright, which causes two problems - you cannot recover the files if they are deleted directly, and some of the items cannot be deleted outright because they are still in use even when all applications are quit.
The next problem is that we'd like to force a restart at the end of uninstall, because some Kerberos processes are still active even though KfM has been uninstalled. However, VISE does not provide a way to force a restart at the end of uninstalls. So we wrote an external code resource called "Restart" that is called on uninstall after we display a message warning the user that we're going to restart.
See also the Really Important Notes section near the top of this document.
The Kerberos for Macintosh installer uses a couple of external code resources to add functionality to VISE. The code for these resources along with compiled binaries is included with the installer distribution. The code resources require CodeWarrior 7.2 to be compiled, although you shouldn't need to make changes to them and recompile them. Here are some brief explanatory notes about them.
Restart
On Mac OS 8 & 9, sends a restart AppleEvent to the Finder. On Mac OS X, sends a restart AppleEvent to the LoginWindow.
Used to force a restart after uninstall in the Mac OS 8 & 9 installer, used to force a restart after both install and uninstall on OS X (VISE's restart is unreliable on OS X).
Timebomb
Displays a dialog warning that the installer will expire on a certain day, and once that day arrives, tells the installer to refuse to run.
Installers that contain development and prerelease versions of KfM include and call the Timebomb code. Final versions do not. The installer source distribution does not include references to the Timebomb external code resource or the code resource itself.
VISE allows you to put UNIX shell scripts in resources that can then be called by your installer to do specialized tasks. The Kerberos for Macintosh installer uses a couple of these. See the VISE manual for information on how they are created; the ones used by the KfM OS X installer are included in the file "UntarShellScripts.rsrc" in the "External Code Resources" folder. The shell scripts are simply text stored as a resource, you should be able to read and edit them (although editing should not be necessary) using ResEdit or Resourceror.
These shell scripts have absolute paths in them to refer to the files in question.
untar Kerberos.framework
Calls kfmtar to untar the Kerberos.framework.tar.
untar Kerberos includes
Calls kfmtar to untar the Kerberos /usr/include headers.
Questions or comments? Send mail to macdev@mit.edu
Last updated on $Date: 2003/11/19 20:36:46 $
Last modified by $Author: smcguire $