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
University of Illinois IT Pros leveraging Technology Services Endpoint Services' Munki Mac Endpoint Management
- General Information
- Workflow Components
- Using the Workflow
- Workflow Actions
- Removing Workflow Components from Manifests
- Skipping the Setup Assistant
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.
The erase-and-install workflow includes the following packages:
- Apple’s macOS installers, but with added features to a) erase the hard drive and b) install several pre-staged packages at /Users/Shared. This package is the "eraser".
- A "requester" package that writes a file to /Library/EPS; without this file, the workflow won't run. This additional package provides an extra measure of protection against accidental erasure.
- Three packages that will be staged at /Users/Shared for later installation by the macOS installer:
- A "stopper" package that will write a file to /Library/EPS; when present, it prevents the re-deployed Mac from launching right back into the installation workflow.
- The UofI MTM Installer for Munki and Multi-Tenant Munki settings.
- A package to bootstrap Munki and restart the Mac.
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:
- request_erase_and_install_macOS_big_sur (this is the "requester")
- erase_and_install_macOS_big_sur (this will run Apple's macOS installer)
To erase the drive and install macOS 10.15, add:
- request_erase_and_install_macOS_catalina (this is the "requester")
- erase_and_install_macOS_catalina (this will run Apple's macOS installer)
To erase the drive and install macOS 10.14, add:
- request_erase_and_install_macOS_mojave (this is the "requester")
- erase_and_install_macOS_mojave (this will run Apple's macOS installer)
To erase the drive and install macOS 10.13, add:
- request_erase_and_install_macOS_high_sierra (this is the "requester")
- erase_and_install_macOS_high_sierra (this will run Apple's macOS installer)
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.
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.
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.
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.
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.