macOS Erase and Install Fileset (Erase Optional)

Description

Upgrading macOS or performing an erase-and-install workflow both require a full macOS installer app. This Fileset is designed to support either case.

Historically, these workflows were split across two KB articles. This newer Fileset can handle either option from one Fileset, and it also removes some older requirements, such as the hidden upgrade file in /var/db.

Ingredients

• Custom Field – "macos_instal_flag"
• Full Apple macOS Installer App
• Provided Recipe
• Provided Custom Field

Fileset:

Custom Field:

softwareupdate --fetch-full-installer --full-installer-version 12.0

softwareupdate --list-full-installers

Directions

Fileset

1. Download and import the provided Fileset
2. Download the desired version of the macOS Installer App
3. Add the macOS installer app to the same folder as the .placeholder file. You can remove the .placeholder file afterward if desired
4. Select the Install macOS app > Get Info > Verification, choose Ignore At Verify, and then Apply to Enclosed
5. Edit the Environment Variables for both the Activation Script and the Requirements Script

Fileset Contents

Environment Variables

The Environment Variables must be edited, providing appropriate values

• M1 devices add an extra requirement when scripting the installation of macOS installer apps. In that case, a local macOS administrator username and password must be passed to the script. Update the local_admin and admin_pass variables accordingly. Intel devices ignore these values if they are set.

Application Token Location

The FileWave Administrator's Application Token (base64) can be found under FileWave Central -> Assistants -> Manage Administrators.

Custom Field

Custom Field has 4 options:

• NA – default value, the Fileset will not do anything with this setting
• ERASE – the device will have the OS erased and install the provided version of macOS
• INSTAL – the device will upgrade to the provided version of macOS
• FAILED – the device will update the Custom Field flag to FAILED if something unexpected occurs.  No further attempts to run the Fileset will action anything whilst this is still the case

Either 'Assign to all devices' or select appropriate devices to associate the Custom Field.

Consider making Smart Group associations based upon the Custom Field value

Activation

Create a Smart Group based upon macos_instal_flag value being either ERASE or INSTAL

Set the associated Custom Field for a device to one of these two values depending upon the experience you would desire.

Selecting a group of devices to associate and/or alter the Custom Field value, will action that new value for all devices currently within that group.  The video shows an example of setting the Custom Field value as INSTAL, with the 2 devices within the macOS 10.13 group.  

Using a group in this way will have no impact on the Custom Field values for devices leaving or joining the group afterward.

Since it is likely a subsequent installation attempt will be desired upon failure (once the reason for failure has been addressed, e.g. not enough disk space), a Smart Group could be set with the Custom Field value of FAILED if desired.

To re-run a failed attempt, after addressing the reason for the failure (e.g. freeing up disk space), reset the Custom Field value to the appropriate ERASE or INSTAL value and choose to 'Reinstall Fileset'

Notes

Why does this Fileset use a Custom Field?

While the Fileset is associated, it may trigger the workflow again. After an erase, for example, the device no longer retains local state about the original installation attempt. Without another control, the device could try to repeat the workflow after it comes back. The Custom Field prevents repeat erase or upgrade attempts once the process is complete, and it also provides a simple way to track failures.

By creating a FAILED value, devices can also report unsuccessful attempts automatically, which makes it easier to build queries or Smart Groups for follow-up.

By setting the macOS Installer App as leave behind, if the installation has not been completed, but is no longer associated, this will ensure the installer remains on the device for subsequent attempts.  Additionally, since Apple automatically removes the macOS Installer App after an upgrade, if the Fileset were still associated there would be no re-attempt to download the installer.

Filesets that error will automatically re-attempt installation as standard.  The requirement script is designed to report an exit code of 210 to overrule this.  Even if the Requirement Script fails, it will report success and will neither continue download/activation nor will it re-attempt without intervention.  In this case, the client will update the Custom Field instead to report the failure.  The script log should show the output of the command.

Example log message:
/usr/local/etc/macos_instal.log

|main|CUSTOM|CLIENT|startosinstall_requirements Exiting. Flag set as:

In this example, the Custom Field Flag reported has no value.  This should either mean the Custom Field is not associated with the device or the script has failed to read the value.  If the latter, check the Environment Variables to ensure they are correct.