This project is no longer under development.
macOS 10.12.4 broke createOSXinstallPkg. Update to the current GitHub code to regain partial functionality: you will not be able to add additional packages, and you'll have to provide your own copy of brtool
from previous macOS Sierra installer apps or older createOSXinstallPkg-created packages.
Due to Apple changes, it's likely-to-virtually-certain that some functionality of createOSXinstallPkg is gone forever: nothing we do will bring back the ability to insert additional packages to be installed.
I think it's probably better longer-term for the community to focus on new tools and new workflows using the startosinstall
binary inside the Install macOS.app. Munki 3 supports this workflow.
If you need to install macOS with additional packages, I suggest you continue using createOSXinstallPkg with a 10.12.3 installer, and then allow Apple Software Update to upgrade machines to 10.12.4 and beyond.
This tool allows you to create an installer package from an "Install OS X.app" or an InstallESD.dmg. You can use this package to install OS X on an empty partition, but perhaps more interestingly, you can also use it to upgrade existing OS X installations to a newer version of the OS X. There are many tools and workflows that support the installation of Apple packages; you can use these together with an OS X installation package to upgrade machines to the latest version of OS X.
This is especially interesting when used with tools like Munki -- you can automate the upgrade of a group of machines while still preserving user data, or offer an upgrade as a "Self-Service"-type option where a user can initiate an OS X upgrade themselves without needing to have administrative rights.
Please read this important 10.10+ note
This toolset, which includes:
createOSXinstallPkg
Resources/installosxpkg_postflight
You may put the toolset anywhere you'd like, but keep the Resources folder and its contents in the same directory as createOSXinstallPkg
.
You'll also need an installation source for OS X (10.7 through 10.11 currently supported): a copy of the "Install Mac OS X Lion.app", "Install OS X Mountain Lion.app", "Install OS X Mavericks.app", etc, install application you can get from the Mac App Store.
Finally, and most importantly, you'll need the rights to install the OS X version on the machines you manage. Just because this tool allows you to create an OS X installation package does not mean it is legal for your organization to install it on all your Macs.
(Since Mavericks, Yosemite, and El Capitan are free, one assumes you can install them with abandon. However, I am not a lawyer, and this does not constitute advice or a recommendation.)
You must run createOSXinstallPkg
with root privileges.
sudo ./createOSXinstallPkg --source /path/to/Install\ OS\ X\ Mountain\ Lion.app
This creates an installation package in the current directory named InstallOSX_[version]_[build].pkg
, where "version" and "build" are the version and build numbers of the OS X version that will be installed.
sudo ./createOSXinstallPkg --source /path/to/Install\ OS\ X\ Mountain\ Lion.app --output /path/to/some/directory/
sudo ./createOSXinstallPkg --source /path/to/Install\ OS\ X\ Mountain\ Lion.app --output /path/to/output.pkg
Adding the --output
option allows you to specify an alternate location and/or name for the output package.
sudo ./createOSXinstallPkg --source /path/to/Install\ Mac\ OS\ X\ Lion.app --pkg /path/to/LocalAdmin.pkg --pkg /path/to/DisableSetupAssistant.pkg
The --pkg
option allows you to add one or more packages to be installed after the OS is installed. You may specify multiple packages. They will be installed in the order given at the command line.
sudo ./createOSXinstallPkg --source /path/to/Install\ Mac\ OS\ X\ Lion.app --identifier 'com.example.installosx.pkg'
The --identifier
option allows you to change the package identifier, which is by default 'com.googlecode.munki.installosx.pkg'.
sudo ./createOSXinstallPkg --plist /path/to/xml.plist
Options to createOSXinstallPkg
can be stored in a plist file. This allows you to save the "ingredients" and "recipe" for a package for future reuse.
Example plist:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Source</key>
<string>/Volumes/Data/Applications/Install OS X Mountain Lion.app</string>
<key>Output</key>
<string>/Volumes/Data/OSX_Install_Packages</string>
<key>Packages</key>
<array>
<string>/Volumes/Data/Packages/LocalAdminAcct.pkg</string>
<string>/Volumes/Data/Packages/DisableSetupAssistant.pkg</string>
<string>/Volumes/Data/Packages/munkitools-0.8.3.1610.0.mpkg</string>
<string>/Volumes/Data/Packages/munki_kickstart.pkg</string>
</array>
<key>Identifier</key>
<string>com.example.installmountainlion.pkg</string>
</dict>
</plist>
If an option is specified in the plist and also explicitly at the command-line, the command-line "wins". (Note this means also that since multiple packages can be specified, that packages in a plist and packages at the command-line are not merged; the packages given at the command-line are the only packages used.)
The package generated by createOSXinstallPkg
is a 'payload-free' package -- that is, it does not install anything from the traditional Archive.pax.gz payload found in most packages. Instead, the real work is done as a package postflight script located at [PACKAGE]/Contents/Resources/postflight
.
The postflight script performs the actions that the GUI "Install Mac OS X Lion" or "Install OS X Mountain Lion" application does when you choose to install OS X.
Those actions are:
OS X Install Data
directory at the root of the target volume.InstallESD.dmg
disk image.kernelcache
and boot.efi
files from the disk image to the OS X Install Data
directory. (The kernelcache
is copied to the Recovery HD helper partition if the target volume is encrypted with FileVault 2.)InstallESD.dmg
disk image.InstallLion.pkg
is on the same volume as the target volume, create a hard link to the InstallESD.dmg
disk image in OS X Install Data
, otherwise copy the InstallESD.dmg
disk image to that directory.com.apple.Boot.plist
file in the Mac OS X Install Data
directory which tells the kernel how to mount the disk image to use for booting. (This file is instead created on the the Recovery HD helper partition if the target volume is encrypted with FileVault 2.)minstallconfig.xml
file, which tells the OS X Installer what to install and to which volume to install it. It also provides a path to a MacOSXInstaller.choiceChanges
file if one has been included in the package.index.sproduct
file and an OSInstallAttr.plist
in the OS X Install Data
directory. These are also used by the OS X Installer.bless
command to cause the Mac to boot from the kernel files copied to the OS X Install Data
directory.diskutil list
).Since most of the work is done with a postflight script, and since that script may need to do a lengthy copy of around 4GB of data (if the package is not on the target volume), you may see a long delay at the "Running package scripts" stage of installation. This is normal. (Annoyingly, the Installer.app displays "Install time remaining: Less than a minute" for several minutes during this stage.)
The next step would be to reboot, but the postflight script does not do this; it just exits. The package is marked as requiring a reboot, so whatever mechanism is used to install the package is responsible for rebooting as soon as possible after the install.
Upon reboot, the machine boots and runs the OS X Installer just as if you had run the "Install Mac OS X Lion" or "Install OS X El Capitan" application manually. It creates or updates a "Recovery HD" partition and installs OS X on the target volume, displaying the OS X Installer GUI. When installation is complete, the machine reboots a second time, this time booting from the new OS X installation.
A "Distribution" file, located at InstallOSX.pkg/Contents/distribution.dist
controls the InstallCheck and VolumeCheck logic.
createOSXinstallPkg
copies InstallCheck and VolumeCheck logic from the OSInstall.mpkg found in the Install.app or InstallESD.dmg. This means that the resulting package will use the same logic as Apple when deciding if a machine/volume is a valid install destination. (One exception -- createOSXinstallPkg
disables the check for command-line installs; without disabling this check you would not be able to install Lion or Mountain Lion using Munki or ARD or any other mechanism that uses the command-line /usr/sbin/installer
.)
The distribution.dist
declares the install size is 8388608 KB (8 1024 1024 KB, or 8GB), which should prevent attempted installation on volumes with less than 8GB free space. You can edit this number if you'd like.
You'll find a MacOSXInstaller.choiceChanges
file at InstallOSX.pkg/Contents/Resources/OS X Install Data/MacOSXInstaller.choiceChanges
See man installer
for more info on ChoiceChangesXML files.
The most likely customization you will want to do is to add additional packages to be installed after the OS install. Some examples might include a package that keeps the Setup Assistant from running when the machine first starts up under Lion, or a package that triggers your software installation management system to run, check for, and install any updates on the first boot after OS X is installed.
Additional packages are added to the InstallOSX.pkg by using the --pkg
option to createOSXinstallPkg
:
sudo ./createOSXinstallPkg --source /path/to/Install\ Mac\ OS\ X\ Lion.app --pkg /path/to/LocalAdmin.pkg --pkg /path/to/DisableSetupAssistant.pkg
You can specify multiple packages. They will be installed in the order given.
The OS X install environment is very stripped down. There are many command-line tools that are not available when booted into this environment. Python and Ruby are not available, either. This can affect pre- and postflight scripts in packages. You may find that some packages that rely on pre- or postflight scripts to perform important tasks will fail to run properly in the OS X install environment. Check the install log at /var/log/install.log after the install is complete, or open the log window during installation to monitor pre- and postflight scripts.
This issue may limit which packages you can use successfully in the OS X installation environment. You should carefully audit and pre- and post- scripts in any packages you add to your install to be certain they will run correctly in the OS X install environment.
To get an idea what tools are available in the OS X install environment, boot into the Recovery HD. The tools available in this environment are the same as those available in the OS X Install environment.
An additional limitation: the InstallESD.dmg volume has a limited amount of free space. To date, that space has been around 350MB. This is more than enough for some basic configuration/bootstrapping packages. But don't try to add Microsoft Office or iLife or Adobe Photoshop CS6. Not only are they too big to fit in the available space, they all contain pre- and post- scripts that are almost certain to fail in the OS X install environment.
The best approach for additional packages is to add only what is necessary to boot the machine and connect it to your software deployment system -- Munki, Casper, Absolute Manage, etc, and let the software deployment system take over and install everything else once the machine is booted into a full OS.
Apple has made an undocumented change in Yosemite that affects this tool. If you add any additional packages for installation as part of the OS install/upgrade, they must all be distribution style packages; not component packages.
If you have an existing flat component pkg, you can convert it into a distribution pkg:
productbuild --package /path/to/component.pkg /path/to/distribution.pkg
I have not tested bundle-style distribution pkgs; would be interested to know if those are supported as well.
If there are additional packages that the OS X installer does not like, this will result in an error dialog upon reboot:
Failed to open OS X Installer.
The path /System/Installation/Packages/OSinstall.mpkg appears to be missing or damaged.with two buttons: "Restart" and "Startup Disk"
The same issue affects customized NetInstall images created with System Image Utility.
If you add additional packages to a customized NetInstall of 10.10 or 10.11, they must be distribution -style packages, or you get the same error.
Installing Lion, Mountain Lion, Mavericks, Yosemite or El Capitan requires a reboot after the install is set up, but before the actual OS X Installer runs. When installing to a FileVault-encrypted volume, after the initial reboot, the pre-boot unlock screen appears. Someone will have to manually unlock the FileVault-encrypted volume before the actual OS X installation can occur. Once the disk is unlocked, installation should proceed normally. Apple's Install OS X.app does some undocumented (and probably non-third-party-supported) magic to cause an authenticated reboot; this bypasses the pre-boot unlock screen.
If your software deployment tool supports doing an authenticated reboot on Filevault-encrypted machines, you should select that option to avoid this issue. (JAMF Casper is one such tool.)