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
The EPS Mac team provides a set of packages based on Apple-supported functionality to provide a Munki-based method for erasing a hard drive, installing (or reinstalling) macOS 10.15 or higher, and re-onboarding the device into Multi-Tenant Munki. This workflow is supported on Intel-based hardware only, and not on Apple Silicon devices.
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 will only work on Intel hardware, not Apple Silicon. And because Apple's installers can't be used to "roll back" macOS, this workflow is also subject to the same restriction. In other words, if you try running the macOS 11 erase-and-install workflow on a device already running macOS 12, 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.
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 12 (Monterey), add:
- request_erase_and_install_macOS_monterey (this is the "requester")
- erase_and_install_macOS_monterey (this will run Apple's macOS installer)
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 (Catalina), add:
- request_erase_and_install_macOS_catalina (this is the "requester")
- erase_and_install_macOS_catalina (this will run Apple's macOS installer)
Remember to visit the MTM web portal and reopen the Mac's certificate window, so that it can be onboarded to MTM.
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.
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.