design/librarymacinstallerplan.mdwn

   1 ##Plan Mac Installer for GSS EAP and SASL GS2 libraries
   2 ###Introduction:
   3 This document describes Codethink's plan for producing an installer for the Moonshot GSS EAP and SASL GS2 libraries for Mac OS X 10.6 (“Snow Leopard”) and 10.7 (“Lion”). The installer will include the libraries and all dependencies, and will perform any configuration necessary to allow the libraries to be used.
   4
   5 The Moonshot GSS EAP library implements the EAP mechanism for use by the GSS API. The GSS API is implemented by the Kerberos implementation which ships with Mac OS (but see Issues below).
   6
   7 The SASL GS2 Library implements the GS2 GSS-API->SASL bridge mechanism for use by the SASL2 library.
   8
   9 The document describes the goals, activities, deliverables and milestones for the development. It also gives some background on the intended locations of the files to be installed, system configuration modifications and any other pertinent information.
  10 ###Goals
  11 The primary goal is to allow users to install, in a single operation, everything they need to start using Moonshot. This includes:
  12
  13 * the Moonshot GSS EAP library;
  14 * the SASL GS2 Library;
  15 * the (re-architected) Identity Selector software (currently referred to a moonshout-ui).
  16
  17 The installer for the Identity Selector software will be delivered as part of the implementation of the architectural changes to the software (due 31st December), so the current task will deliver only the first two.
  18
  19 We will deliver this goal incrementally, by developing sub-packages for cyrus_SASL, Moonshot EAP library and Identity selector, and combining them into a meta-package.
  20
  21 allow users to install the libraries on a computer running Mac OS X without needing to build them from source. Once installed, the libraries can be used to provide authentication services to programs which use them.
  22
  23 Secondary goals are
  24
  25 1. To allow developers and users who are familiar with the Mac OS build tools chain to install, as well as build, the libraries using these tools on a computer running Mac OS X. (This is currently possible for the Cyrus SASL library and plugins, but not for the Moonshot GSS EAP library).
  26 2. To automate (as far as possible) and document the process of making the installer, allowing Moonshot project developers to easily produce installer packages for future versions of these libraries.
  27
  28 ###Deliverables:
  29 1. Changes to files if required to allow the Moonshot GSS EAP library to be installed, as well as built, under Mac OS using autotools.
  30 2. An installer package (or packages) that, when run, will install the necessary files to the required places in the files system. (See Outstanding questions/issues 1).
  31 3. A compressed disk image file containing the installer package(s), which can be mounted to run the installer package. (See Outstanding questions/issues 2)
  32 4. Instructions and scripts for creating the installers and disk images from source. The scripts will use the [*packagemaker* tool](https://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/packagemaker.1.html) to build the installer packages and the [*hdiutil* tool](https://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/hdiutil.1.html#//apple_ref/doc/man/1/hdiutil) to create and to manipulate disk images.
  33
  34 ###Activities and Milestones
  35 1. Build and install the Cyrus SASL GS2 Library for Mac OS using autotools to prove this currently works and that it is a valid goal for the Moonshot GSS EAP library. Due Wednesday 16th November.
  36 2. Create an installer package and compressed disk image for the Cyrus SASL Library, with notes on how to achieve the process. Due Friday 18th November.
  37 3. Make the necessary changes to the Moonshot GSS EAP library source and configuration files to build and install it for Mac OS using autotools. Due Friday 25th November.
  38 4. Create an installer package and compressed disk image for the Moonshot GSS EAP library. Due Tuesday 29th November.
  39 5. Create the scripts and instructions. Due Wednesday 30th November.
  40
  41 ###Issues and questions
  42 ####To be resolved during implementation
  43 Q: Pete> Which files in which directories?
  44 > A: Pete (21-Nov-2011)> SASL GS2 library - all files in /Library/Frameworks/SASL2.framework: GSS EAP library - in gss subfolder of Kerberos Installation: Kerberos - tbd.
  45
  46 ####Resolved Issues (I think)
  47 Q: Pete> One package each for "Snow Leopard" and "Lion", or a single package that works for both? One disk image each for "Snow Leopard" and "Lion", or a single disk image containing both packages?
  48 > A: Pete (21-Nov-2011)> A single metapackage, containing sub-packages for each component. (SASL GS2, GSS EAP, Identity Selector, Kerberos)
  49
  50 Q: Sam> One of the big questions will be to what extent will you use system dependencies and to what extent will you package your own. You'll want to look over the build instructions Josh pointed you at. If you're packaging the acceptor, then all of the dependencies on the preparation page as well as everything built by the builder script apply.If you're packaging an initiator, you need Kerberos and not much else.
  51 > A: Pete> My inclination for the Mac installer is as far as possible to use what ships with the OS - in this case Heimdal for Lion - but to include anything else in our installer - even if it *may* already be installed to support another program.
  52
  53 > update 21-Nov-11 Pete> We will need to package a more recent Kerberos, both for Snow Leopard and Lion. We will build the latest stable release (1.9.2) from [MIT](from http://web.mit.edu/kerberos/dist/index.html). Moved the issue to 'Resolved'
  54
  55 Q: Sam> One of the big questions will be whether you can use the system Kerberos.  My assumption is that you cannot for 10.6.  You may be able
  56 to do so for 10.7. This will be one of the big open questions we're expecting the plan to answer.
  57 > A: Pete> Googling for 'mac os X Lion Heimdal' gives a worrying number of forum posts about problems. I'm concerned that we could end up spending time debugging 'Lion's Heimdal' which is not what you are paying us for! My inclination for the Mac installer is as far as possible to use what ships with the OS - in this case Heimdal for Lion - but to include anything else in our installer - even if it *may* already be installed to support another program. So for Lion, we should start by using Heimdal, but if we hit problems then, rather than spending a long time tracking down the problem, our first step would be to try whatever we used for Snow Leopard.
  58
  59 > Josh> Sounds like a plan
  60
  61 > Pete> Further information in the mailing list at https://www.jiscmail.ac.uk/cgi-bin/webadmin?A2=ind1111&L=MOONSHOT-COMMUNITY&D=0&X=09511F3D9F0F762A88&Y=pete.fotheringham%40codethink.co.uk&P=12159 and https://www.jiscmail.ac.uk/cgi-bin/webadmin?A2=ind1111&L=MOONSHOT-COMMUNITY&D=0&X=09511F3D9F0F762A88&Y=pete.fotheringham%40codethink.co.uk&P=13011
  62
  63 > update 21-Nov-11 Pete>See above Moved the issue to 'Resolved'
  64
  65 Q: Luke> What's the actual framework binary (that is, /Library/Frameworks/Moonshot.framework/Moonshot) going to link to -- libmoonshot-ui? That would make the most sense as mech_eap and the GS2 SASL plugin aren't directly linked against by applications. By convention, you'll need to have something there (otherwise it's not really a framework).
  66 > A: Pete> I was wrong - Moonshot GSS EAP is not a framework, and we won't create /Library/Frameworks/Moonshot.framework. Instead the libary will be installed in the /gss subfolder of the Ketberos Installation
  67
  68 Q: Pete> New issue - do we need to do the versioning as suggested in the plan, or can we just overwrite the existing installation?
  69 >A: Pete> The library isn';t a framework and is not linked to directly by apps, so we don't need versioning.
  70
  71 Q: Sam> What prevents moonshot gss eap from being built using autotools today? It's my understanding that Luke does this regularly.
  72
  73 Q: Luke> As Sam said, I'm not exactly sure what you meant about building with autotools. Were you talking about building with the autotools that ship with OS X? (That may not be possible.) Or a script that invokes autoconf with the appropriate arguments to install in the Mac filesystem hierarchy? Because I do all my development on OS X and I haven't had any problems with autotools and Moonshot (no more than one might usually have).
  74 > A: Pete> No problems that I know with *building* but I didn't think it could be *installed* in Mac OS using 'configure && make install' as can be done with the Cyrus SASL. I think that would be a useful secondary goal for this piece of work.
  75
  76 Q: Pete> Which libraries?
  77 >A: Josh> the SASL library is self-contained within cyrus-sasl.
  78
  79 > Sam> I think our changes have all been folded upstream at this point.
  80
  81 > Sam> the moonshot directory contains the GSS-EAP library
  82
  83 > Pete> so the SASL library is cyrus-sasl/libsasl2 and the GSS_EAP library is moonshot/mech_eap
  84
  85 Q: Sam> Does their SOW involve packaging all the dependencies for an acceptor build or  an initiator only build?
  86 > A: Josh> It might be prudent to work towards an initiator-only build, at least initially, as this significantly reduces the size of the problem. The message for Pete is to obtain sufficiently new krb5, the moonshot project from the git repo, and build an initiator from those? I'm pretty sure we don't need a Mac acceptor.
  87
  88 Q: Luke> The framework directory should surely be Moonshot.framework, not Moonshot, if it indeed is a framework
  89 > A: Pete> Agreed. Document changed
  90
  91 Q: Luke> org.janet should be net.ja (unless janet.org is registered to JANET?)
  92 > A: Pete> Document changed
  93
  94 Q: Luke> Are you planning to install Cyrus SASL as a separate framework?
  95 >A: Pete> Yes. Installing Cyrus SASL to /Library/Frameworks/SASL2.framework (as in the existing 'make install'). I have changed the plan to reflect this
  96
  97 ###Background information
  98 ####Installer functionality:
  99 There are two parts to the installation:
 100
 101 1: The installer will install library and header files in /usr/local/lib and /usr/local/include, as for the Linux 'make install'.
 102
 103 2: SASL2 Framework: in addition, the installer will install Cyrus SASL framework will be installed in /Library/Frameworks/SASL2.framework (as in the existing Cyrus SASL 'make install' and as recommended by Apple's guidelines to developers). The framework is a wrapper for a symlink to the dynamic library in /usr/local/lib/libsasl2.dylib and mech_eap.dylib.
 104
 105 If an installation of the SASL library with a lower version number is present, the new installation will be installed.
 106
 107 If an installation with a higher version number is present, the new installation will terminate with a message explaining why.
 108
 109 If an installation with the same version number as version being installed is present, a message is displayed to the User asking them to confirm whether the existing installation should be overwritten?
 110
 111 The User will not be able to configure the installation to install only some of the components.
 112
 113 The exact text to be used in messages displayed to the user will be specified as part of the implementation of the installer.
 114
 115 The appearance of the installer will not be customized to use special icons and window backgrounds.
 116
 117 ###Package and Component Properties
 118 The Package properties will be
 119
 120     Provider Identifier (Organization): net.ja.moonshot
 121     Target OS (Minimum Target): Mac OS 10.6 Snow Leopard
 122
 123 For each component in the package, properties will be
 124
 125     Destination (To): The appropriate directory
 126     Custom destination consent (Allow custom location): False.
 127     Package identifier: net.ja.moonshot.xxxx (where xxx identifies the individual library)
 128     Package version number: 1 for first release, incremented in future releases
 129     Finalization action (Post-install): None
 130     Administrator-authentication requirement (Require admin authorization): True
 131     Relocatable: False
 132     Downgradeable: False
 133     No pre- or post-installation scripts are planned (but this may change during implementation)
 134     The owner will be root and the group admin. The owner, group, and access permissions of the component files will be determined during implementation.
 135 (See Ref.2 for an explanation of these properties)
 136 ####Delivered components and files
 137 The installer will install the following libraries:
 138 #####Moonshot GSS EAP Library
 139 This library consists of the following files installed in the following locations:
 140 To be completed (See Outstanding questions/issues 3)
 141 <table border="1">
 142 <tr>
 143 <td>File</td> <td>location</td> <td>notes</td>
 144 </tr>
 145 <tr>
 146 <td>mech_eap.dylib</td> <td>/usr/local/lib/gss</td> <td>The dynamic library</td>
 147 </tr>
 148 <tr>
 149 <td>gssapi_eap.h</td><td>/usr/local/include/gssapi</td> <td>header file for the EAP GSS mechanism</td>
 150 </tr>
 151 </table>
 152 The following configuration files will be modified:
 153 <table border="1">
 154 <tr>
 155 <td>File</td> <td>change</td> <td>notes</td>
 156 </tr>
 157 <tr>
 158 <td></td> <td></td> <td> </td>
 159 </tr>
 160 </table>
 161
 162
 163 #####Cyrus SASL Library and GS2 plugin
 164 The following files will be installed in the following locations:
 165 To be completed (See Outstanding questions/issues 3)
 166
 167 Plugins go in /usr/lib/sasl (which should be a symlink to /usr/local/lib/sasl).
 168
 169 <table border="1">
 170 <tr>
 171 <td>File</td> <td>location</td> <td>notes</td>
 172 </tr>
 173 <tr>
 174 <td>sasl2.dylib</td> <td>/usr/local/lib/</td> <td> </td>
 175 </tr>
 176 <tr>
 177 <td>Sasl2</td> <td>/Library/Frameworks/SASL2.framework</td> <td>The framework binary - symlink to /usr/local/lib/libsasl2.dylib</td>
 178 </tr>
 179 <tr>
 180 <td>??</td> <td></td> <td> </td>
 181 </tr>
 182 </table>
 183
 184 The following configuration files will be modified:
 185 <table border="1">
 186 <tr>
 187 <td>File</td> <td>change</td> <td>notes</td>
 188 </tr>
 189 <tr>
 190 <td></td> <td></td> <td> </td>
 191 </tr>
 192 </table>
 193
 194 #####Dependencies
 195 The installer will not include any dependencies which are present by default in the installed version Mac OS X.
 196
 197 For any dependencies which are not present by default in the installed version Mac OS X, the installer will install the needed versions.
 198 ###References:
 199 1. [Mac OS X Developer Library, Framework Programming Guide, Installing Your Framework](https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Tasks/InstallingFrameworks.html#//apple_ref/doc/uid/20002261-BBCCFBJA)
 200 2. [Mac OS X Developer Library, PackageMaker User Guide](https://developer.apple.com/library/mac/#documentation/DeveloperTools/Conceptual/PackageMakerUserGuide/)