Skip to content
This repository has been archived by the owner on Dec 12, 2023. It is now read-only.

startosinstall Notes

Jump to bottom
Greg Neagle edited this page Dec 22, 2017 · 20 revisions

Table of Contents

Introduction

Imagr can install macOS High Sierra (10.13) to a target volume via the new startosinstall workflow component. You may target an empty volume or volume containing data or a volume containing an OS, just as if you install macOS "by hand."

TL;DR

Requirements

  • "Install macOS High Sierra.app" wrapped in a disk image, available via http/https. You can create such a disk image like so:

    sudo hdiutil create \
    -srcfolder /Applications/Install\ macOS\ High\ Sierra.app ~/Desktop/Install_macOS_High_Sierra.dmg

  • 10.12.6 or 10.13 NetInstall-style nbi, such as that built via autonbi and/or the make nbi support that is documented here: Automatic Creation and Makefile Override and Manual Creation

Workflow

    <key>workflows</key>
    <array>
        <dict>
            <key>components</key>
            <array>
                <dict>
                    <key>type</key>
                    <string>startosinstall</string>
                    <key>url</key>
                    <string>http://imagr.fake.com/installers/Install%20macOS%20High%20Sierra-10.13.dmg</string>
                </dict>
            </array>
            <key>description</key>
            <string>Installs High Sierra.</string>
            <key>name</key>
            <string>Install High Sierra</string>
        </dict>
    </array>

url must point to a disk image containing an Install macOS.app at the root.

This must be the last component in a given workflow; startosinstall will force a restart when it finishes setting up the macOS install; no subsequent workflow components will be executed.

Optional additional_startosinstall_options

        <dict>
            <key>type</key>
            <string>startosinstall</string>
            <key>url</key>
      	    <string>http://imagr.fake.com/installers/Install%20macOS%20High%20Sierra-10.13.dmg</string>
            <key>additional_startosinstall_options</key>
            <array>
                <string>--converttoapfs</string>
                <string>NO</string>
            </array>
        </dict>

Optional additional_package_urls:

        <dict>
            <key>type</key>
            <string>startosinstall</string>
            <key>url</key>
            <string>http://imagr.fake.com/installers/Install%20macOS%20High%20Sierra-10.13.dmg</string>
            <key>additional_package_urls</key>
            <array>
                <string>http://imagr.fake.com/pkgs/AdminAccount.pkg</string>
                <string>http://imagr.fake.com/pkgs/SuppressSetupAssistant.pkg</string>
                <string>http://imagr.fake.com/pkgs/munkitools.pkg</string>
                <string>http://imagr.fake.com/pkgs/munki_kickstart.pkg</string>
            </array>
        </dict>

Additional package notes and Apple bugs

Additional packages must be flat distribution-style packages. I did not find they needed to be signed.

Apple Bugs

As of 10.13 release, specifying more than one additional package appears to be broken; startosinstall doesn't seem to properly stage all the packages.

Paths for all given packages are added to macOS Install Data/InstallInfo.plist under the "Additional Installs" key, but not all are actually copied to the paths indicated. When the machine restarts after the macOS install is set up, the installer complains that "The path /System/Installation/Packages/OSInstall.mpkg appears to be missing or damaged." and tells you to restart and try again.

If you then restart to a different volume (locally attached or a network boot) you can see the problem. I tried to install four additional packages. macOS Install Data/InstallInfo.plist lists all four:

    <key>Additional Installers</key>
    <array>
        <string>UnwrappedInstallers/78d4e18c246101ac030409a3b28cf1ba6006055e/Adminaccount.pkg</string>
        <string>UnwrappedInstallers/56609c54df6cc13597ea94d2ffd30540d7027dc7/SuppressSetupAssistant.pkg</string>
        <string>UnwrappedInstallers/a04a3ba6f46deddca73b98679d09d2e41a95b2fa/munkitools.pkg</string>
        <string>UnwrappedInstallers/6a0b81670c8f340ee2c51c98aa0572f5a8aa055b/munki_kickstart.pkg</string>
    </array>

but the actual UnwrappedInstallers directory only has two of the packages:

$ ls -al macOS\ Install\ Data/UnwrappedInstallers/
total 0
drwxr-xr-x   4 root  wheel  136 Oct 11 10:11 .
drwxr-xr-x@ 16 root  wheel  544 Oct 11 10:13 ..
drwxr-xr-x   3 root  wheel  102 Oct 11 10:12 56609c54df6cc13597ea94d2ffd30540d7027dc7
drwxr-xr-x   3 root  wheel  102 Oct 11 10:12 6a0b81670c8f340ee2c51c98aa0572f5a8aa055b

I can manually copy the missing packages to the paths listed in InstallInfo.plist and then if I restart into the macOS Installer environment, install proceeds successfully and the extra packages are installed, although with some UI bugs.

One other bug: The additional packages are installed after the machine boots into the new OS for the first time. The mechanism that does the install appears to ignore the restart flag if it's set on any of the packages. I included the munkitools.pkg in my additional packages. It was successfully installed, but since there was no reboot after its install, Munki bootstrapping didn't actually work or kick in until after I manually restarted the machine one more time.

Assuming Apple eventually fixes these bugs, this should be a really useful way to deploy. But until then...

Update: you can workaround the first bug by ensuring all the extra packages are distribution packages that contain unique "product id"s. See https://managingosx.wordpress.com/2017/11/17/customized-high-sierra-install-issues-and-workarounds/ for more information.

Alternate workflow with additional packages

Since there are serious bugs in 10.13's startosinstall with regard to additional packages, I currently recommend an alternate workflow:

    <dict>
        <key>components</key>
        <array>
            <dict>
                <key>first_boot</key>
                <true/>
                <key>type</key>
                <string>package</string>
                <key>url</key>
                <string>http://imagr.fake.com/pkgs/Adminaccount.pkg</string>
            </dict>
            <dict>
                <key>first_boot</key>
                <true/>
                <key>type</key>
                <string>package</string>
                <key>url</key>
                <string>http://imagr.fake.com/pkgs/SuppressSetupAssistant.pkg</string>
            </dict>
            <dict>
                <key>first_boot</key>
                <true/>
                <key>type</key>
                <string>package</string>
                <key>url</key>
                <string>http://imagr.fake.com/pkgs/munkitools.pkg</string>
            </dict>
            <dict>
                <key>first_boot</key>
                <true/>
                <key>type</key>
                <string>package</string>
                <key>url</key>
                <string>http://imagr.fake.com/pkgs/munki_kickstart.pkg</string>
            </dict>
            <dict>
                <key>type</key>
                <string>startosinstall</string>
                <key>url</key>
                <string>http://imagr.fake.com/installers/Install%20macOS%20High%20Sierra-10.13.dmg</string>
            </dict>
        </array>
        <key>description</key>
        <string>Installs High Sierra, installing additional packages at first boot.</string>
        <key>name</key>
        <string>Install High Sierra 2</string>
    </dict>

Package components must be installed prior to the startosinstall component. This is due to startosinstall triggering a reboot.

This workflow uses package components that install at first boot. These are cached on the target disk (which might be empty to start) and then a macOS install is kicked off.

Be sure to test that the user experience is acceptable for you -- it might be confusing what is happening at first boot depending on the exact packages being installed.

Testing notes

In the same directory as the imagr repo, make a config.mk file. Recommended contents:

BUILD=Testing
STARTTERMINAL=True
APP="/Applications/Install macOS Sierra.app" # if you are building on Sierra
APP="/Applications/Install macOS High Sierra.app" # if you are building on HS
URL="http://imagr.fake.com/test_workflows.plist" # substitute your URL
INDEX="5007" # substitute your index
NBI="startosinstall_testing_Imagr" # substitute your nbi name

(Don't put/leave any comments in your config.mk -- they are there in this document to help explain things.)

Working from the directory containing the Makefile (typically the root of your cloned Imager repo), run make nbi to build a (NetInstall-style) nbi containing Imagr. Transfer the resulting nbi (which is by default created on your Desktop) to your NetBoot server and perform the needed incantations to get your NetBoot server to offer this nbi.

Since we set STARTTERMINAL=True in the Makefile override, when this nbi boots it will open a terminal window instead of starting Imagr. This lets us see logging and debugging info. Launch Imagr like so:

/System/Installation/Packages/Imagr.app/Contents/MacOS/Imagr

To test later updates to the code, you don't have to go through the lengthy make nbi process again; you can just do make update as long as you left a copy of the nbi in its original location (again, Desktop by default). You'd then copy the updated nbi to the NetBoot server and test again.

More details

SIP and startosinstall

In order to install to volumes other than the current boot volume, startosinstall must be run from a machine with SIP disabled, or from a boot environment that ignores SIP. A NetInstall-style nbi is such an environment, and is the type of nbi generated by autonbi.
Other nbi-building tools (Example: AutoImagrNBI) may result in boot environments that do not ignore SIP and that will not work with the startosinstall component.

startosinstall and 10.12.6

Testing of startosinstall to install 10.12.6 Sierra was unsuccessful. Please continue to use existing deployment workflows for 10.12.

Introduction

Configuration

NetInstall

OS Installation

External Drive

Target Disk Mode

RAM Disk

Further Resources

Clone this wiki locally