Legacy 7. Erasing and reinstalling macOS
Use the --erase parameter to initiate the erase and reinstall of the system volume.
If the --erase parameter is used alone, erase-install.sh will check for a cached installer in the working directory and in /Applications. If it finds one, it will use this installer for the erase-and-reinstall process described below. If it does not find one, it will download the latest compatible installer for the system on which the script is running. This is also compatible with the --fetch-full-installer and --pkg parameters described elsewhere.
The erase-and-reinstall process calls startosinstall --eraseinstall (startosinstall is a command-line tool included in the macOS installer app).
The startosinstall command requires user credentials to be supplied when run on an Apple Silicon Mac. When running this script on an Apple Silicon Mac, the user will be prompted to enter a username and password via osascript dialogs. The script checks that the user exists, is a "Volume Owner", and that the password is correct.
You can reduce the number of dialogs by adding the --current-user parameter to pre-select the logged-in user.
You can reduce the number of dialogs by adding the --user parameter to pre-select a user, for example --user ladmin or --user=ladmin.
There is currently a reported bug affecting the startosinstall process on Apple Silicon Macs, which results in the system going into RecoveryOS when the system is manually rebooted the first time after a reinstallation is completed. An administrator account must be selected, and then the password entered. After a couple of seconds the authentication is done and the device can boot normally again.
Therefore, this script may not be appropriate for use on headless Mac computers, until this bug is fixed.
UPDATE: there are reports that this is fixed in macOS 11.5.
macOS Big Sur requires 45 GB of spare drive space to perform an upgrade or erase-and-reinstall. If this space is not available, the user is informed via an osascript dialog and the script ends.
This figure is lower on older versions of macOS. You can override the default minimum space required for startosinstall to run with the --min-drive-space=NN or --min-drive-space NN parameter, where NN is a value in GB. Example --min-drive-space 30.
If you wish to install some packages after macOS is installed, you can put them in a folder and they will be picked up by the startosinstall command. Please note that only signed packages can be installed using startosinstall.
The default location is a folder named extras in the working directory, i.e. /Library/Management/erase-install/extras. If you want to point to a different directory, you can supply the path with the --extras key, e.g. --extras /Users/Shared/extra-packages or --extras=/Users/Shared/extra-packages.
If the system has the jamfHelper tool installed (jamfHelper is installed when enrolling into Jamf Pro), a notification message is displayed during the download process. Once the download is complete, the window is closed and the script moves on to the erase-and-reinstall process described below.
If DEPNotify is installed, and the --depnotify parameter is used, a notification message is displayed using DEPNotify.
If you wish for the user of the computer to confirm that they wish to erase the device before startosinstall is called, add the --confirm parameter. This will bring up a dialog either using jamfHelper, DEPNotify or a native osascript dialog asking the user to confirm that they wish to proceed. With jamfHelper and osascript dialogs, the default button is the "Cancel" button. With DEPNotify this is not possible as only one button can be displayed.
This is the message shown with jamfHelper:
This is the message shown with osascript:
This is the message shown with DEPNotify:
Once the erase-and-reinstall process is ready to begin, another dialog is launched. On Jamf Pro enrolled Macs, this is a full-screen jamfHelper window:
For Jamf users testing the script, you can add the --no-fs parameter to switch to a utility window instead of the full screen window. Or, you can use the --no-jamfhelper to switch to the osascript dialogs.
Cmd+Q will quit any jamfHelper dialog.
If jamfHelper is not available, an osascript dialog is shown instead:
If the --depnotify parameter is used, and DEPNotify is installed on the client, a full-screen DEPNotify window is used:
Ctrl+Cmd+X will quit the DEP Notify dialog.
There are various additional parameters that can customise the erase-and-reinstall workflow.
You can specify a specific OS, version or Build ID to download using the --os, --version or --build parameters. You can keep to the same OS as the current system using the --sameos parameter. You can keep to the same Build ID using the --samebuild parameter. See the section on downloading a specific version for more details of how these parameters work.
You can place any signed packages in a folder named extras in the working directory. These packages will be installed on the system as part of the erase-and-reinstall process. These packages must be signed.
The path to search for these packages can be overridden with the --extras argument:
sudo /path/to/erase-install.sh --erase --extras /path/containing/extra/packages
If the --check-power option is used, the script will check if the computer is connected to AC power. If it isn't, it will wait for a default of 60 seconds for power to be added, and otherwise fail.
The default time to wait can be altered by setting the --power-wait-limit option, e.g. --power-wait-limit 180 for 3 minutes.
This is the dialog if jamfHelper is available:
This is the osascript dialog:
This parameter enables you to supply a shell command to run immediately prior to startosinstall running. An example might be:
--preinstall-command "jamf recon -department Spare"
Ensure that the command is in quotes.
For testing out the script, you can add the --test-run parameter. This runs through the entire workflow up to but not including the startosinstall command. Instead, a sleep 120 command is run.