Endpoint Services, Munki, Erase-and-Install Workflow

This article provides guidance on using an Apple-supported, erase-and-install workflow for a clean macOS installation.

Looking to instead perform an in-place macOS upgrade without disturbing user data? Here's how.


Munki Mac Endpoint Management

Affected Customers

University of Illinois IT Pros leveraging Technology Services Endpoint Services' Munki Mac Endpoint Management


General Information

Beginning with the release of macOS 10.13 (High Sierra), Apple stopped supporting traditional imaging techniques. However, with the release of the macOS 10.13.4 installer, Apple introduced a new, supported method for erasing an APFS-formatted hard drive and reinstalling macOS. Optionally, additional packages may be pre-staged on the hard drive, to be installed after the new OS is in place.

The EPS Mac team has created a set of packages based on this Apple-supported functionality, which provide a Munki-based method for erasing a hard drive, reinstalling macOS 10.13.6 or higher, and re-onboarding the device into Multi-Tenant Munki.

Limitations: because this workflow relies on functionality built into Apple's macOS installers, it is only supported on Macs already running 10.13.4 or higher with an APFS-formatted hard drive, or on Macs running 10.14.0 or higher with either an APFS or an HFS-formatted drive. Additionally, it can only be used to install macOS 10.13.6 or higher, and will only work on Intel hardware, not Apple Silicon. Lastly, because Apple's installers can't be used to "roll back" to an older OS, this workflow is also subject to the same restriction. In other words, if you try running the 10.15 erase-and-install workflow on a Mac running 11 (Big Sur), it will fail.

Workflow Components

The erase-and-install workflow includes the following packages:

Using the Workflow

To erase the drive and install macOS on an eligible Mac running 10.13.4 or higher with an APFS-formatted drive, add the following to the Managed Installs array of the machine's serial number manifest. The EPS team strongly recommends *against* adding the workflow to shared or included manifests, in order to avoid accidental drive erasure and subsequent data loss.

To erase the drive and install macOS 11 (Big Sur), add:

To erase the drive and install macOS 10.15, add:

To erase the drive and install macOS 10.14, add:

To erase the drive and install macOS 10.13, add:

Remember to visit the MTM web portal and reopen the Mac's certificate window, so that it can be onboarded to MTM.

Workflow Actions

The first time Munki runs, it will offer the requester along with all other components except for the eraser itself, which won't be installed until the requester is in place. This is intended to provide an extra measure of protection against accidental workflow deployment and data loss.

First Munk Run

The next time Munki runs, it will offer the eraser. It will also re-offer some workflow components that were previously installed; this is a harmless side-effect of the component dependencies. If you wish to avoid this scenario for any reason, add the requester to the manifest by itself first, and once it installs, add the eraser.

Next Munki Run

Once the macOS installer has been downloaded (which may take a few minutes), Managed Software Center will prompt for a restart, after which the macOS installer will run. Depending on the age of the hardware, this may take an hour or more.

Finally, the staged packages will install and the Mac will reboot. Walk through the setup assistant per your usual deployment method. After logging in, you may either manually run Managed Software Center, or immediately logout and allow the bootstrapping file to run Munki at the login window. If you have reopened the Macs' certificate window, it will onboard to MTM, find its manifest, and start downloading and installing content.

Note that the machine manifest still contains the eraser and the requester, but Munki won’t offer either for re-installation after the workflow is complete. This is because of the “stopper” component, which wrote a file at /Library/EP/stop_erase_and_install_macOS_[version].txt. As long as the stopper file remains in place, the workflow will not be reinitiated, and no accidental drive erasure should occur.

Removing Workflow Components from Manifests

In theory, after the workflow completes, the machine's Munki manifest may be left unchanged, with both eraser and requester items remaining in the Managed Installs array, because the stopper file will prevent their reinstallation. However, it is safest and cleanest to a) delete the eraser item from the manifest, and b) move the requester item from the Managed Installs array to the Managed Uninstalls array. Uninstalling the requester will also delete the stopper file; if you simply delete the requester from the manifest rather than uninstalling it, the stopper file will be left on the machine, preventing future workflow runs and likely causing confusion down the road.

Skipping the Setup Assistant

In response to stakeholder request, a modified version of the Big Sur and Catalina workflows have been created that will skip all Setup Assistant steps and boot directly to the login window: erase_and_install_macOS_big_sur_skip_setup_assistant and erase_and_install_macOS_catalina_skip_setup_assistant. Unless you have alternate methods for creating local admin accounts, do not use these workflows, as there will be no accounts created and therefore no way to log in.

Contact the EPS team