osxke-installer-doc.html [plain text]
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
<title>Mac OS X Kerberos Extras Installer Documentation</title>
</head>
<body bgcolor="white">
<center>
<h1>Mac OS X Kerberos Extras Installer Documentation</h1>
<h3>Current as of Installer Revision 12</h3>
</center>
<h2>Table of Contents</h2>
<ul>
<li><a href="#Overview">Overview </a>
<li><a href="#GeneralRequiremtns">General Requirements</a>
<li><a href="#SystemRequirements">System Requirements of Components</a>
<li><a href="#FileGuide">Packages</a>
<li><a href="#CustomLocations">Custom Install Locations</a>
<li><a href="#FileGuide">Guide to Files & Action Items</a>
<li><a href="#Notes">Installer Notes</a>
<li><a href="#shellscript">Shell Script Resources</a>
</ul>
<h2><a name="Overview"></a>Overview</h2>
<p>The Mac OS X Kerberos Extras package includes add-ons for the built-in Kerberos
on Mac OS X 10.2 or 10.3 that allows it to work with CFM-based Kerberos using
applications such as Eudora and Fetch, and makes an alias to the GUI Kerberos
management application in a more convenient location. Also included is a configuration
file preconfigured for MIT.</p>
<p>The .vct archive provided with this project shows how these components are
installed by the Mac OS X Kerberos Extras installer that MIT distributes.</p>
<p>If you have any questions or comments, please send them to <<a href="mailto:krbdev@mit.edu">krbdev@mit.edu</a>>
. </p>
<h2><a name="SystemRequirements"></a>System Requirements of Components</h2>
<h3>Installer</h3>
<p>The minimum system required for the components installed is Mac OS X 10.2.</p>
<p>The .vct requires Mindvision Installer VISE 8.0.2 or later.</p>
<h2><a name="Anchor"></a>Packages</h2>
<p>There are two packages: <strong>Easy Install</strong> and <strong>Install New
Configuration File</strong>.</p>
<p><strong>Easy Install</strong> installs the Kerberos CFM support library, places
an alias to the GUI Kerberos management application in <code>/Applications/Utilities</code>
(the Kerberos application ships in <code>/System/Library/CoreServices</code>
), and <code>edu.mit.Kerberos</code> (the Kerberos configuration file), if one
doesn't exist already (see below for locations). At the end it calls a couple
of shell script external resources to set file permissions.</p>
<p><strong>Install New Configuration File</strong> will force the installation
of a new Kerberos configuration file (<code>edu.mit.Kerberos</code>), moving
any existing one to the Trash and putting a fresh copy in its place. Instead
of the user having to choose Custom Install to get to this package, it's set
to appear in the install pop-up directly.</p>
<h2><a name="CustomLocations"></a>Custom Install Locations</h2>
<p>The Mac OS X Kerberos Extras installer, like the KfM 4.0.3 for OS X installer,
needs to install and find files in Mac OS X directories that are not part of
VISE's standard install locations, such as the <code>/System</code> locations.
So we 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.</p>
<p>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 <code>ExternalCodeResources:KfMLocations:KfM
Locations</code> from the installer source distribution to the "Install
Locations" subfolder of your VISE application's folder before making any
changes to the installer.</p>
<p>This is basically the same external code we used for the KfM 4.0.3 for OS X
installer, with a couple of additional locations. As such, many of the custom
locations aren't used by the Kerberos Extras installer.</p>
<p>The custom install locations are:</p>
<p><code>Temporary/Old KfM Files<br>
/System/Library/Authenticators<br>
/System/Library/CFMSupport<br>
/System/Library/Frameworks</code><code><br>
/System/Library/CoreServices<br>
/Library/Preferences<br>
/Library/Receipts<br>
/usr<br>
/usr/bin<br>
/usr/include<br>
/usr/lib<br>
/private/var/root/.Trash </code></p>
<p>The only two used in the Kerberos Extras installer are <code>/System/Library/CFMSupport</code>
and <code>/System/Library/CoreServices .</code></p>
<p>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.</p>
<h2><a name="FileGuide"></a>Guide to Files & Action Items</h2>
<p>In the table below, actual files and folders are displayed in <b>bold</b>,
whereas action items names are displayed in <i>italics</i>. Each action item
has a definition of what it does, and then an explanation of why it does this
(except for comment "action" items).</p>
<p>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.</p>
<p>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).</p>
<p>
<table width="100%" border="1">
<tr>
<td><b>Files</b></td>
<td><b>Install To:</b></td>
<td><b>Replace</b></td>
<td><b>Gestalts</b></td>
<td><strong>Packages</strong></td>
</tr>
<tr>
<td><p><i>Message Action Item: Message OS X Too New</i></p>
<p>If the installer is run on an OS whose version is Mac OS X 10.4 or greater
(a check made using a custom Gestalt, based on an educated guess about
what the next Mac OS version will be at a minimum), this action item displays
a warning message that the Kerberos Extras are not supported on this unknown
version of Mac OS X and thus the installer will not continue.</p>
<p>Since we don't know what features of KfM future OS X versions will hold,
we don't want to install these Extras which are specifically tailored
to 10.2 and 10.3 on them.</p></td>
<td>n/a</td>
<td>n/a</td>
<td>Mac OS X 10.4 or Greater</td>
<td>Easy Install</td>
</tr>
<tr>
<td> <p><i>Stop Action Item: Stop Mac OS X Too New</i></p>
<p>If the installer is run on an OS whose version is Mac OS X 10.4 or greater
(a check made using a custom Gestalt, see above), this action item brings
the installation to a halt before it can begin.</p></td>
<td>n/a</td>
<td>n/a</td>
<td>Mac OS X 10.4 or Greater</td>
<td>Easy Install</td>
</tr>
<tr>
<td><em>Comment Action Item: --Trash Old Kerberos.app</em></td>
<td>n/a</td>
<td>n/a</td>
<td>n/a</td>
<td>n/a</td>
</tr>
<tr>
<td> <p><em>Move Action Item: Trash old Kerberos.app Appl</em></p>
<p>Searches<code> /Applications</code> for a folder named Kerberos.app (the
Kerberos application is a Mach-O bundled application), and moves it to
the Trash if found.</p>
<p>This removes previous versions of the Kerberos application that might
be left around from KfM 4.0 if the user upgraded from Mac OS X 10.1 instead
of clean-installing 10.2/10.3.</p></td>
<td>n/a</td>
<td>Always (Rename Existing)</td>
<td> </td>
<td>Easy Install</td>
</tr>
<tr>
<td> <p><em>Move Action Item: Trash old Kerberos.app Util</em></p>
<p>Searches <code>/Applications/Utilities</code> for a folder named Kerberos.app
(the Kerberos application is a Mach-O bundled application, and thus, a
folder), and moves it to the Trash if found.</p>
<p>This removes previous versions of the Kerberos application that might
be left around from KfM 4.0 if the user upgraded from Mac OS X 10.1 instead
of clean-installing 10.2/10.3.</p></td>
<td>n/a</td>
<td>Always (Rename Existing)</td>
<td> </td>
<td>Easy Install</td>
</tr>
<tr>
<td> <p><em>Comment Action Item: --Delete Old Bridge Libraries</em></p></td>
<td>n/a</td>
<td>n/a</td>
<td>n/a</td>
<td>n/a</td>
</tr>
<tr>
<td> <p><i>Delete Action Item: Delete old Kerberos.bridge</i></p>
<p>Looks in <code>/System/Library/CFMSupport</code>, System Domain for a
file whose name is "Kerberos.bridge" and file type/creator is
'<code>shlb</code>'/'<code>Krb </code>' and deletes it.</p>
<p>This removes an out of date CFM support library (it was renamed for Mac
OS X 10.2). The old bridge libraries will never be useful on 10.2 or later,
so we just get rid of them.</p></td>
<td>n/a</td>
<td>n/a</td>
<td><i></i></td>
<td>Easy Install</td>
</tr>
<tr>
<td> <p><i>Delete Action Item: Delete Kerberos Support.bridge</i></p>
<p>Looks in <code>/System/Library/CFMSupport</code>, System Domain for a
file whose name is "Kerberos Support.bridge" and file type/creator
is '<code>shlb</code>'/'<code>Fuzz</code>' and deletes it.</p>
<p>This removes an out of date CFM support library (it was renamed and combined
into one file for Mac OS X 10.2 and later). The old bridge libraries will
never be useful on 10.2 or later, so we just get rid of them.</p></td>
<td>n/a</td>
<td>n/a</td>
<td> </td>
<td>Easy Install</td>
</tr>
<tr>
<td><em>Comment Action Item: --Install CFM support library</em></td>
<td>n/a</td>
<td>n/a</td>
<td>n/a</td>
<td>n/a</td>
</tr>
<tr>
<td><b>Kerberos</b></td>
<td>/System/Library/CFMSupport , System Domain</td>
<td>Always</td>
<td> </td>
<td>Easy Install</td>
</tr>
<tr>
<td><em>Comment Action Item:--Make alias to Kerberos.app</em></td>
<td>n/a</td>
<td>n/a</td>
<td>n/a</td>
<td>n/a</td>
</tr>
<tr>
<td><p><em>Alias Action Item: Alias Kerberos.app to /Appl/Uti</em></p>
<p>Places an alias to Kerberos.app, the GUI Kerberos management application
in <code>/Applications/Utilities</code> - the Kerberos application ships
in Mac OS X 10.2 and later in <code>/System/Library/CoreServices</code>
.</p></td>
<td>n/a</td>
<td>Always</td>
<td> </td>
<td>Easy Install</td>
</tr>
<tr>
<td><em>Comment Action Item:--Install simple config file</em></td>
<td>n/a</td>
<td>n/a</td>
<td>n/a</td>
<td>n/a</td>
</tr>
<tr>
<td> <p><b>edu.mit.Kerberos</b></p>
<p>Don't replace existing configuration files which are probably valid.</p></td>
<td>Preferences Folder, Local Domain</td>
<td>Never</td>
<td> </td>
<td>Easy Install</td>
</tr>
<tr>
<td><em>Comment Action Item:--Install New Config File</em></td>
<td>n/a</td>
<td>n/a</td>
<td>n/a</td>
<td>n/a</td>
</tr>
<tr>
<td><p><em>Message Action Item: Config Replace Warning</em></p>
<p>Warns the user that choosing to install this package will replace their
existing configuration file and lose any modifications they've made, do
they want to proceed?</p></td>
<td>n/a</td>
<td>n/a</td>
<td> </td>
<td>Install New Config File</td>
</tr>
<tr>
<td><p><em>Move Action Item:Trash edu.mit.Kerberos</em></p>
<p>Searches<code> /Library/Preferences</code> (specified by using the location
Preferences Folder, Local Domain) for a file named <code>edu.mit.Kerberos</code>
, and moves it to the Trash if found.</p>
<p>This is a simple backup if the user suddenly decided they didn't want
to do this even after the dialog made sure.</p></td>
<td>n/a</td>
<td>Always (Rename Existing)</td>
<td> </td>
<td>Install New Config File</td>
</tr>
<tr>
<td><p><strong>edu.mit.Kerberos</strong> (VISE shadow item)</p>
<p>Needed another pointer to this file, even though it's installed in the
same place as the one above, because in the "Install New Config File"
package it's set to always replace instead of never replace.</p></td>
<td>Preferences Folder, Local Domain</td>
<td>Always</td>
<td> </td>
<td>Install New Config File</td>
</tr>
<tr>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
<td> </td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
</table>
<p></p>
<h2><a name="Notes"></a>Installer Notes</h2>
<h3>Special Installer Settings</h3>
<blockquote>
<p><b>Require OS X Authentication</b> (Attributes tab of "Installer Settings")
- Since the installer installs (and deletes) 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.</p>
</blockquote>
<h3>Installation Location of "edu.mit.Kerberos" File</h3>
<blockquote>
<p>The <code>edu.mit.Kerberos</code> configuration file may be found in two
locations on a Mac OS X volume, the system configuration in <code>/Library/Preferences</code>
and the user configuration in <code>/User/userid/Library/Preferences</code>
. The MIT installer installs the <code>edu.mit.Kerberos</code> 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 <a href="http://web.mit.edu/macdev/Development/MITKerberos/Common/Documentation/preferences-osx.html">Kerberos
Preferences on Mac OS X Documentation</a> for a full explanation.</p>
</blockquote>
<h2><a name="shellscript"></a>Shell Script Resources</h2>
<p>VISE allows you to put UNIX shell scripts in resources so that can then be
called by your installer to do specialized tasks. The Mac OS X Kerberos Extras
installer calls a couple of these at the end of the install to set file permissions
and owners correctly. (VISE allows you to set file's permissions and group,
but not owner, and only allows you to do this for files which the installer
is installing, not for pre-existing files). See the VISE manual for information
on how they are created; the ones used by the Kerberos Extras installer are
included in the file "ChangePermissions.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 Resource.</p>
<p>These shell scripts have absolute paths in them to refer to the files in question.</p>
<p>They are called at the end of the installer by setting the External Codes:After
Install settings in the "Extras" section of the "Installer Settings."
</p>
<p>It is important that your installer call these shell scripts, otherwise it
may compromise the security of the system the software is installed on.</p>
<p><strong>Chown CFM Support Library</strong></p>
<blockquote>
<p>Changes the Kerberos CFM support library to have: owner root, group wheel,
permissions u=rwx g=rx o=rx. This is consistent with other system-level software.</p>
</blockquote>
<p><strong>Chown edu.mit.Kerberos</strong></p>
<blockquote>
<p>Changes the edu.mit.Kerberos configuration file to have: owner (user who
is installing), group admin, permissions u=rw g=rw o=r . This will also fix
up the permissions on any existing edu.mit.Kerberos file.</p>
</blockquote>
<!-- #include "footer.html" -->
<HR>
<P>
<FONT SIZE="+1"> <B>
Questions or comments? Send mail to <A HREF="mailto:macdev@mit.edu">macdev@mit.edu</A>
</B> </FONT> <BR>
Last updated on $Date: 2003/09/10 19:17:12 $ <BR>
Last modified by $Author: smcguire $<BR>
</P>
<!-- Begin MIT-use only web reporting counter -->
<IMG SRC="//counter.mit.edu/tally" WIDTH=1 HEIGHT=1 ALT="">
<!-- End MIT-use only web reporting counter -->
</BODY> </HTML>
<!-- end include -->