INTRO ----- Terminology note: We'll be interchanging "NetBoot" with "NetInstall" through these documents. Everything is actually about doing a network install. In reality, a NetInstall is just a NetBoot that runs Installer.app instead of the normal OS boot sequence. SimpleNetInstall (SNI) is a system with a few goals in mind to improve Apple's standard NetInstall process: - Authenticate the people doing the installs (so people couldn't plug-in i and steal our licensed software) - Offer different configurations for different departments - Offer a choice of loadsets within each department - Pre-configure the machine's hostname and first user account - Pre-configure the 4 custom text fields for Apple Remote Desktop (ARD) - Keep server costs low - Be able to update packages without rebuilding the whole NetBoot image These goals are satisfied using two main changes to Apple's stock NetInstall process: - When a machine is NetBooted, rather than going directly to the Installer application, an intermediate window (SNI) appears prompting for department information and authentication - The packages that will be installed on a system are stored on an AFP server rather than being included inside the NetBoot image itself PREREQUISITES ------------- You'll need the following servers for everything to work: - NetBoot server(s) - WebServer - AFP server(s) These need not be separate boxes. Additionally, you'll want someone who has the following skills to configure and maintain the system: - Strong shell and perl scripting knowledge - Comfortable in UNIX and on the command-line - Very experienced in Apple pkg creation - Familiar with Apple server software - Very experienced in plists Since NetInstall/NetBoot requires the server to see a client's broadcast traffic, you'll either need a NetBoot server on the same subnet as your clients, or you'll need to make arrangements to NetBoot across subnets. Here at the University of Michigan, we've gone the route of having our network administrators create DHCP Helper Addresses for each subnet that we'll be NetBooting from. There are other options available out there. For more information, see Mike Bombich's guide to NetBooting Across Subnets: http://www.bombich.com/mactips/ INSTALLATION ------------ Webserver Configuration: SNI gets its configuration information from a webserver. Copy the webserver-samples directory to your webserver and configure the plists in that directory to meet your needs. Start with the parents.plist, which define each of your available AFP servers. For each AFP server, you need to define a children-server.plist. The children-server.plist lists the departments/groups that are available from that server. For each department, you need to also create a dept.plist which defines the loadsets available for that department. If you want to utilize multiple departments but only use the same loadsets, making symlinks of the dept.plists is a good way to go. parents.plist keys for each server dict: Children URL: HTTP URL of that server's children-server.plist Display Name: Human readable name of the server in the SNI menu (note that the Display Name may be used to describe the function of the server and need not be the DNS name - the DNS name will also be displayed to the user after they select the server in SNI) Server Name: DNS name of the AFP server Share Name: AFP share name that will be mounted as /Parent during install children-server.plist keys for each department dict: Display Name: Human readable name of the department in the SNI menu Loads URL: HTTP URL of that department's dept.plist Server Name: DNS name of the AFP server for that department share Share Name: AFP share name that will be mounted as /Child during install dept.plist for each department: Display Name: Human readable name of the load as shown in the SNI menu OS: File path to the top level collection file for total OS installs AppsOnly: File path to the top level collection file for Apps-only installs Dist Modification Dir: File path to the directory containing distribution file changes for that loadset (described later) A collection file is a short XML file that lists what top-level metapackages are installed and in what order. The first package needs to be listed twice (I don't know why). Here's a sample (OS.collection): /Parent/Packages-Leopard/DVD-Packages/OSInstall.mpkg /Parent/Packages-Leopard/DVD-Packages/OSInstall.mpkg /Parent/Packages-Leopard/LSA-AppleUpdates/AppleUpdates.mpkg /Parent/Packages-Leopard/LSAalterations/LSAalterations.mpkg /Parent/Packages-Leopard/Apps.mpkg /Parent/Packages-Leopard/LSAalterations/useraccount.pkg If you want Kerberos support in SNI, place your edu.mit.Kerberos file in the Resources directory. Make the following changes to it: - only one Kerberos realm (yours) - no AFS or kerberos plugins referenced - short ticket lifetime if you'd like to be a little security paranoid (theoretically, it should only need about a 1 minute ticket lifetime, long enough to mount the shares before the installation) If you don't want Kerberos support in SNI, delete the edu.mit.Kerberos file in the Resources directory SNI Application Configuration: The SNI app needs to know where to find the parents.plist. Modify Resources/SimpleNetInstall.app/Contents/Resources/parents.url to contain the URL of your parents.plist file. If you'd like to put any sort of tracking information, just add it after the ? in the URL - it should be ignored by your webserver. We use it to track the current version of SNI being used. NOTE: be sure there's no line ending in this file after you edit it. You can verify this by typing wc -l Resources/SimpleNetInstall.app/Contents/Resources/parents.url If it comes back with '0', you're OK - if it comes back with a number greater than 0, you have extra line endings in the file. The easy way to create the file without a line ending is using this command: echo -n "http://your.web.server/path/to/parents.plist" > Resources/SimpleNetInstall.app/Contents/Resources/parents.url SNI includes functionality to get the full name and UID of the first user that is created on a machine from an LDAP server. This is done in two parts. The first part just checks the existence of a given user in the LDAP directory, and also looks up their full name and UID for your reference (though they are not actually used). You'll want to modify Resources/SimpleNetInstall.app/Contents/Resources/username.pl to do this based on your local LDAP directory or other system used for doing username lookups. If a valid user is found, SNI will create a file during installation at /tmp/user_create that contains the username and their shadow-hash password (already hashed, but missing the leading and trailing zeros). This file is read by the useraccount.pkg during installation which then does another LDAP lookup to retrieve all of the relevant information and actually create the user. You'll need to modify that package to suit your local needs as well. SNI includes a debug drawer, that, when opened, will execute all of the commands listed in Resources/SimpleNetInstall.app/Contents/Resources/debugCommands.sh Feel free to modify it if desired. Next, modify the Resources/rc.cdrom.local file to point to your local NTP server - this is especially important if you're using Kerberos, as it may be the first time a target machine has its clock set and Kerberos requires 5-minute accuracy on the system clock. BUILDING YOUR NETBOOT IMAGE You are now ready to build your NetBoot Image Create a normal NetInstall image based off the latest OS installation disc you have using System Image Utility using default settings for everything. Once that's complete (it'll take somewhere in the ballpark of 30 minutes), run the "RUN-ME" script found in this directory. It will prompt you for the location of the DMG found inside the .nbi folder created by System Image Utility, and will take care of all the necessary modifications to customize it for SNI. AFP SERVER DIRECTORY STRUCTURE ------------------------------ You need to create at least 2 AFP shares that will house your packages. The first will be what is mounted as /Parent on the target machine. This share contains packages common to every installation, such as the OS packages, Apple software updates, and applications available to every machine. You also need to create additional shares, which will be mounted as /Child on the target machine. Create a share for each department that will be set up in SNI. After creating the directories, change the group ownership and permissions of that directory so only members of a given group have access to that share. Example: At our installation, here's the directory setup we have on our AFP server: This will be mounted at /Parent on the target machine: drwxr-x--- 27 root lsa-installers /Volumes/DataDisk/Install/LSA/ Depending on the department/group selected in SNI, one of these will be mounted at /Child on the target machine: drwxrwx--- 12 root astr /Volumes/DataDisk/Install/Group/astr/ drwxrwx--- 4 root bio /Volumes/DataDisk/Install/Group/bio/ drwxrwx--- 4 root chem /Volumes/DataDisk/Install/Group/chem/ drwxrwx--- 4 root math /Volumes/DataDisk/Install/Group/math/ PARENT CONTENTS: Inside the Parent folder (LSA in our case), we create a few main folders: Apps-Common (applications for any OS) Apps-Panther (10.3 specific packages) Apps-Tiger (10.4 specific packages) Apps-Leopard (10.5 specific packages) Packages-Panther (10.3 OS packages) Packages-Tiger (10.4 OS packages) Packages-Leopard (10.5 OS packages) Though you could certainly create whatever folder structure you'd like. Inside Packages-Leopard, we place all of the OS packages found on the installation DVD. To grab those packages, follow these steps: Insert the system install DVD. % open /Volumes/OS_INSTALL_CD/System/Installation/Packages/ Copy all of the packages to your AFP share. In the individual department.plist configuration files you created earlier, a path was specified that led to the main OS or AppsOnly top-level collection. At this point, make a duplicate of the OSInstall.mpkg and put it at that location. In our installation, we put it at: Packages-Leopard/OS.collection and Packages-Leopard/APPS.collection One of the packages listed in both of the collections files (in fact, the ONLY package listed in the APPS.collection file) is Apps.mpkg. This is just a normal 10.4-style mpkg with a distribution script. However, we need to make a couple changes inside it. cd into the Apps.mpkg/Contents directory. Rename the dist file that's there to be TEMPLATE.dist. Then, create a symlink under the original dist file name that points to /private/tmp/custom-mpkg.dist This file destination file is created by SNI (by sni-package-munger, actually) during installation. You'll notice above that I said "10.4-style mpkg" - 10.5 adds the ability to use flat pkg files which are just a single file rather than a directory bundle. Although these flat pkg files are great for internet distribution, they aren't compatible with any of my scripts since all the important bits are buried deep within the xar/cpio archive that the flat file really is. As such you should only use 10.4-style packages. If you get a 10.5-style flat file pkg, you can open it in PackageMaker and change it to 10.4-style package and re-save it. So far this seems to work OK for me. Now, in the TEMPLATE.dist, at the bottom of the block, add the following: and, at the bottom of the entire file, but just before the , add During a NetBoot, the rc.cdrom.local script will call the SNI-package-munger script (both found in the Resources folder if you want to look at them) and will substitute department specific content at the magic_substitute_lines/choices_here line. More info about that can be found in the CUSTOMIZING YOUR LOADSET section below. In your main dist file, don't forget to include all of the package information for any of the packages you reference. I've included the files (in Examples/dist-files) we use so you can get an idea of of what things look like. Additionally, you'll notice that there are some additional Javascript functions we've added to the top of the TEMPLATE.dist-universal file. These include useful functions like: isPPC() PPCPhotoBoothAllowed() IntelPhotoBoothAllowed() IntelFrontRowAllowed() iLife04Allowed() iLife05Allowed() iLife06Allowed() To make life easier when you're adding additional packages to the files, we've included a script called pkg-dist-info in the Examples directory that will output cut & paste text about a package. CHILD CONTENTS: The contents of each child/department/group directory is totally up to you. There will be an optional Dist Modification Dir (we use "leopard-load-mods") that will contain the choice-additions and line-additions files for any department-specific customizations to that loadset. The name of that directory was defined in each of the dept.plist configuration files on your webserver. For more information on that, see the CUSTOMIZING YOUR LOADSET section next. Additionally, you can put anything else you'd like that is department specific in this directory, and just reference it on the target machine using the /Child/ path. Examples of this might be software that is only licensed to one department, or a text file with the name of the department that a package script copies onto the target machine for reporting purposes. CUSTOMIZING YOUR LOADSET ------------------------ To get started, once you're inside your group install directory (/Child/), enter the customizations directory. This is leopard-load-mods for our standard 10.5 loads, or it's the directory you specified in the department.plist webserver configuration file. Next, inside that directory, create two plain text files (no extension): choice-additions line-additions You can use any text editor, such as nano -w filename for those that remember pine. Just remember that the filename is important, and it must not contain any extension (like .txt). choice-additions This file is used to change the behavior of an item already available in SNI. To take advantage of it, add a line like this to your choice-additions file: There are two main pieces of that line. The first, is the id of that package (id="OpenAFS" in the above example). This id must correspond EXACTLY (include capitalization) to the id used in the master TEMPLATE.dist file. The second part of the example line contains the options (start_selected="true" in the above example). You can use this option, along with others, to determine the behavior of that package in SNI. start_selected - Is that package 'checked' in SNI? true: packe is installed by default false: package is not installed by default start_enabled - Is that package greyed out in SNI? true: package is enabled - user can toggle the checkbox false: package is disabled - user can't toggle the checkbox. NOTE: You can still determine, via the start_selected option, if this package will be installed, but the person doing the installation won't be able to change it unless it's enabled. start_visible - Should the user even see this package? true: package is shown false: package is hidden NOTE: this does not change whether a package is installed (as defined above). It only determines whether this item is shown to the user during installation selected - similar to the start_selected, but is evaluated after the user clicks something. This is mostly useful when combined with javascript to make settings change based on the selection of another package. enabled - similar to the start_enabled, but is evaluated after the user clicks something. This is mostly useful when combined with javascript to make settings change based on the selection of another package. visible - similar to the start_visible, but is evaluated after the user clicks something. This is mostly useful when combined with javascript to make settings change based on the selection of another package. title - The words that show up next to checkbox in the installer description - The words that show up in the frame at the bottom of the installer when the package is hilited tooltip - Text that will appear near the mouse-pointer when hovering over the checkbox for this package. Here are some examples of a choice-additions that you might use that showcase some of the options. (Each choice should only be on one line - they're word-wrapped here for easier readability): NOTE: You don't have to use ALL of the options. If you don't specify something, it will just use the defaults defined in the TEMPLATE.dist file for the other options. In most cases, you'll probably just want to change the start_selected option. line-additions The line additions file is used to add new packages to the list that don't normally appear in the installer. The choice portion of each line must correspond EXACTLY (include capitalization) to the package id used in the master TEMPLATE.dist file, and is the same as the id field used in the choise-additions file. Here is a list of all the IDs for your convenience. NOTE: Most packages are already in the list for installation. You only need to modify this file if you're adding a new package that doesn't already show up in the installer. That will add all of those packages to be available to your loadset, but they will be unselected. If you're adding your own package that doesn't exist in the default loadset, you'll also need to tell the installer where that package is. To do this you'll need to do the following: Put the new package in your group install directory (/Child/) cd /Volumes/DataDisk/Install/Group/YourDept /usr/local/bin/pkg-dist-info NameOfYourPackage.pkg That will print out the bits and pieces that you'll need to paste into your line-additions and choice-additions files. You'll notice that there is a lot more information that also needs to be specified when you're adding a new package, such as the size, authorization, and the path to the package. Here's a sample: % /usr/local/bin/pkg-dist-info math-common-pkgs/SysDataSender-Math.pkg file:/Child/math-common-pkgs/SysDataSender-Math.pkg The first part, () should be pasted into your line-additions file. The rest, including the pkg-ref line, should all be pasted into your choice-additions file. Don't copy every package to your /Child/ space The only packages you need to copy to your /Child/ space are those that meet either of the following criteria: Package is only used by your department and isn't available to others Package is an older version than what is available to others If you simply want to change the selection default of a package, the ONLY thing you need to do is add one line (per pkg) to your choice-additions file. PREFS SETTING PACKAGES ---------------------- One of the big time savers that we take advantage of are packages that pre-configure a machine to be set up the way we want it. This is especially important in our environment where machines aren't connected to an Open Directory server so we can't use MCX settings for these. Some of these packages simply install a plist in /Library/Preferences, while others run a postflight script to set things up. The key packages that are integrated with SNI include: hostname.pkg (sets machine name based on SNI input) useraccount.pkg (creates the first user based on SNI) DeptInfo.pkg (copies dept info txt file to machine and sets ARD fields) We have a number of other packages that also pre-set a number of settings, and have included these for your reference. Many of them set things specific to our environment, so you should not install them in your environment without first understanding what the package does. Automated Account Creation If you'd prefer that the useraccount.pkg script automatically put an account on a machine rather than you specifying it in the SNI GUI, you can use the included make-account-maker script and add it to your loadset. One caveat is that the script creates the user's password in the much less secure crypt format rather than as a shadow hash. Just run it and follow the instructions on screen. NOTE: You must either create an account in SNI or create an SNI-account-creator package (with make-account-maker) to prevent the apple setup assistant from launching after the machine reboots. TROUBLESHOOTING --------------- If you're having problems connecting to your shares, the first thing to know is that SNI has a debug drawer that can be opened with Apple-D or via the menus at the top. If you're having problems connecting to your Parent or Child shares from SNI, be sure you can connect to them using the same credentials manually through the Finder If a Terminal would help while netbooted, you can touch a file named "run-terminal" in a directory called "SNI-Debug" in your Child directory. For example, in our environment, the file would be located at: /Volumes/DataDisk/Install/Group/lit/SNI-Debug/run-terminal If you need a terminal earlier in the process, you can modify the rc.cdrom.local file to launch a Terminal session in the background. Some packages run scripts that don't account for having a space in the name of the harddrive you're installing on. For interactive installs on the boot volume, this bug may not appear as the target is '/'. However, when doing NetInstalls, the target volume will be something like "/Volumes/Macintosh HD/" - be sure any and all paths in postflight scripts are fully quoted to account for this. Many of Apple's software update packages assume they are being run with a user in front of the screen and on the current boot volume. You may have to modify packages to remove the requirements check that you're installing on the current boot volume, and possibly modify scripts to not make changes to a user's Dock, or remove anything that opens a new GUI application. SUPPORT ------- Unfortunately we have our hands full supporting this ourselves in our environment. We don't have the resources to support other environments, and in order to make this work, you MUST have experts in house that understand all of the concepts outlined here. We made this available because people asked us to, but unfortunately are unable to provide any support for your installations. That said, this certainly provides a great business opportunity for you to provide support to others! FEEDBACK -------- We probably left something out of this document by accident. If you figure out what that is, please let use know by sending an email to lsa-dev-osx@umich.edu # COPYRIGHT 2007 # THE REGENTS OF THE UNIVERSITY OF MICHIGAN # ALL RIGHTS RESERVED # # PERMISSION IS GRANTED TO USE, COPY, CREATE DERIVATIVE WORKS AND # REDISTRIBUTE THIS SOFTWARE AND SUCH DERIVATIVE WORKS FOR ANY PURPOSE, # SO LONG AS NO FEE IS CHARGED, AND SO LONG AS THE COPYRIGHT NOTICE # ABOVE, THIS GRANT OF PERMISSION, AND THE DISCLAIMER BELOW APPEAR IN # ALL COPIES MADE; AND SO LONG AS THE NAME OF THE UNIVERSITY OF MICHIGAN # IS NOT USED IN ANY ADVERTISING OR PUBLICITY PERTAINING TO THE USE # OR DISTRIBUTION OF THIS SOFTWARE WITHOUT SPECIFIC, WRITTEN PRIOR # AUTHORIZATION. # # THIS SOFTWARE IS PROVIDED AS IS, WITHOUT REPRESENTATION FROM THE # UNIVERSITY OF MICHIGAN AS TO ITS FITNESS FOR ANY PURPOSE, AND WITHOUT # WARRANTY BY THE UNIVERSITY OF MICHIGAN OF ANY KIND, EITHER EXPRESS OR # IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF # MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE REGENTS OF # THE UNIVERSITY OF MICHIGAN SHALL NOT BE LIABLE FOR ANY DAMAGES, # INCLUDING SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, # WITH RESPECT TO ANY CLAIM ARISING OUT OF OR IN CONNECTION WITH THE # USE OF THE SOFTWARE, EVEN IF IT HAS BEEN OR IS HEREAFTER ADVISED OF # THE POSSIBILITY OF SUCH DAMAGES. # # If you do make any changes, it would be appreciated if you submitted # them back to lsa-dev-osx@umich.edu